In OData, what does declaring a navigation property with ContainsTarget change about the contained entities' keys, identity and URLs?

## Containment versus an ordinary relationship An ordinary **navigation property** links two independent entities: an order points at a customer that lives in the `Customers` entity set and exists whether or not the order does. A **containment navigation property** - one declared with `ContainsTarget="true"` - says something stronger: instances of the declaring type **contain** the targets, which exist only inside their container. | Aspect | Ordinary navigation | Containment (`ContainsTarget="true"`) | |---|---|---| | Where targets live | Typically a top-level entity set, named by a navigation property binding | An implicit entity set per containing instance | | Key uniqueness | Within the top-level entity set | Within the containing instance's collection | | Canonical URL | `/Customers('C42')` | `/Orders(1001)/Lines(2)` | | Also in a top-level set? | Typically | **MUST NOT** be | | Reachable from several parents? | Yes | Only one containment relationship | ## What containment does to identity and addressing 1. **An implicit entity set per parent.** The CSDL says containment navigation properties "define an implicit entity set for each instance of its declaring structured type", identified by the read URL of the navigation property for that instance. `Orders(1001)/Lines` and `Orders(1002)/Lines` are two different entity sets. 2. **Keys are scoped to the parent.** Because an entity's key identifies it within an entity set, a line's `LineNumber` need be unique only within its order: line 2 can exist in every order. Without containment, the same lines in a top-level `OrderLines` set would need a key unique across all orders - typically a composite key such as `OrderID` plus `LineNumber`, or a service-wide surrogate key. 3. **The canonical URL starts at the container.** The URL conventions define it as the containing entity's canonical URL, then a type-cast segment if the property is declared on a derived type, then the navigation property segment, then the key if the property is collection-valued: `/Orders(1001)/Lines(2)`. 4. **Responses say so.** The context URL of a contained entity names the path through its container, for example `$metadata#Orders(1001)/Lines/$entity`. ## The constraints that come with it - An entity **cannot** be referenced by more than one containment relationship, and **cannot** both belong to an entity set declared in the container and be contained. - Entity types used in a **collection-valued** containment navigation property **MUST** have a key. - A navigation property binding's path may traverse containment navigation properties but **MUST NOT** end in one: contained entities are located by their container, not bound to a set. - Modifying, adding or deleting a contained entity **MAY** change the ETag of the parent entity, so a client holding the order's ETag can see its update rejected after a line changes. ## Partners and recursive containment A containment navigation property **MAY** declare a `Partner` leading back to the container. The CSDL warns that without one "there is no reliable way for a client to determine which entity contains a given contained entity", which bites when the contained entity can also be reached through a non-containment path. Two rules apply: - **Non-recursive containment** (orders containing lines): the partner **MUST NOT** be nullable - every line has an order. - **Recursive containment** (a type containing entities of its own inheritance hierarchy, such as categories containing sub-categories) defines a **tree**: the partner **MUST** be nullable, because the root has no parent, and single-valued, because each non-root node has one. ## When to use it Containment fits data whose identity is meaningless without its owner - order lines, a contract's clauses, the steps of a workflow instance. It buys short, owner-relative keys, URLs that show ownership, and a model that states the lifecycle dependency instead of leaving it to documentation. It costs the ability to treat contained entities as a top-level collection: a client reaches lines only through their orders, for example by reading `/Orders(1001)/Lines` or expanding lines while reading orders. If reporting across all lines is a core use case, an ordinary entity set with a composite key and a navigation property may serve clients better. In **OData 4.01** the target type of a **single-valued** containment navigation property need not declare a key - an order's single `Invoice` can be key-less. OData 4.0 requires a key on every entity type used this way.