diff --git a/OData.Community.Keys.V1.md b/OData.Community.Keys.V1.md index fd206a6..eb0f1c0 100644 --- a/OData.Community.Keys.V1.md +++ b/OData.Community.Keys.V1.md @@ -1,11 +1,11 @@ -#Alternate Keys for OData Services -##A mechanism for OData services to express additional unique key definitions that may be used to address entities. +# Alternate Keys for OData Services +## A mechanism for OData services to express additional unique key definitions that may be used to address entities. -##1 Introduction -###1.1 Summary +## 1 Introduction +### 1.1 Summary This document details a proposal for an OData v4 vocabulary to describe a services ability to have certain entities be addressed by their standard key properties as well as additional sets of properties that make up alternate keys. -###1.2 Background +### 1.2 Background OData v4 currently includes the concept of a key for an entity type that defines the set of columns that make up the unique identifier for an entity. This key is used in the URL that addresses a specific entity instance. For example: ```http @@ -29,14 +29,14 @@ https://host/service/customers(Branch=ABC,CustomerId=123) This concept is missing from current OData specifications. -###1.3 Further Reading +### 1.3 Further Reading OData v4 specifications: http://www.odata.org/documentation/   -##2 Usage Scenarios -###2.1 Client requests service metadata +## 2 Usage Scenarios +### 2.1 Client requests service metadata When metadata-aware clients first retrieve metadata from a service to discover its data model, entity type metadata will be annotated to describe the availability of alternate keys that can be used to address that entity type. -####2.1.1 Alternate Keys Vocabulary +#### 2.1.1 Alternate Keys Vocabulary When a service supports alternate keys, it will annotate entity type metadata to describe the structure of the available alternate keys for each entity type. The AlternateKeys annotation term will contain a collection of key definitions, each of which contain a collection of PropertyRef’s. It will be declared as follows: @@ -72,7 +72,7 @@ They are redefined here as complex types so that they can be used on an annotati The following examples demonstrate how this annotation term would be used to describe different alternate key configurations.   -####2.1.2 Example: Single alternate key with single property +#### 2.1.2 Example: Single alternate key with single property The following metadata described a Person entity type with an alternate key on the SSN string property: ```xml @@ -100,7 +100,7 @@ The following metadata described a Person entity type with an alternate key on t ```   -####2.1.3 Example: Single Alternate Key composed of multiple properties +#### 2.1.3 Example: Single Alternate Key composed of multiple properties The following metadata described a Person entity type with an alternate key defined on the person’s home country and passport number string properties: ```xml @@ -132,7 +132,7 @@ The following metadata described a Person entity type with an alternate key defi ``` -####2.1.4 Example: Single Alternate Key composed of properties from a complex type +#### 2.1.4 Example: Single Alternate Key composed of properties from a complex type The following metadata described a Person entity type with an alternate key defined on the person’s home country and passport number string properties which are part of a complex type. Take note of the required use of the Alias property. ```xml @@ -167,7 +167,7 @@ The following metadata described a Person entity type with an alternate key defi ``` -####2.1.5 Example: Multiple Alternate Keys +#### 2.1.5 Example: Multiple Alternate Keys The following metadata described a Person entity type with two alternate key defined. One key uses the person’s SSN, and the other users their Employee ID. ```xml @@ -205,7 +205,7 @@ The following metadata described a Person entity type with two alternate key def ``` -####2.1.6 Key Declaration Uniqueness +#### 2.1.6 Key Declaration Uniqueness An alternate key is identified by the unique set of properties that are referenced in its declaration, regardless of the order in which properties are listed. Services SHOULD NOT return multiple alternate key definitions for the same entity type that are composed of the exact same set of properties. @@ -214,10 +214,10 @@ Services MAY define keys that contain overlapping properties or that contain all Services SHOULD NOT provide an alternate key definition that exactly matches the property set of the primary entity key.   -###2.2 Client calls a service with alternate keys +### 2.2 Client calls a service with alternate keys When a client wishes to address an operation to an entity using alternate key values, they will provide the property name(s) and values for the intended key in the key segment. -####2.2.1 Key Predicate Formats and Key Matching +#### 2.2.1 Key Predicate Formats and Key Matching OData defines 2 types of key predicates, a simpleKey and a compoundKey as follows: ```http @@ -240,24 +240,24 @@ http://host/service/persons(Country=USA,Passport=9876) (matches alternate key ex If the set of properties does not match a defined key or alternate key, the service should return HTTP Status 400 (Bad Request). -####2.2.2 Use of Alternate Keys +#### 2.2.2 Use of Alternate Keys Alternate key syntax should be supported in all the places that the canonical URL for an entity is used, including in in URL’s for data service requests as well as alternative entity-id’s for bind operations. -#####Address an Entity +##### Address an Entity ```http GET /service/persons(ssn=123-456-7890) HTTP/1.1 PATCH /service/persons(ssn=123-456-7890) HTTP/1.1 ``` -#####Address Contained Entity +##### Address Contained Entity ```http GET /service/road(90)/exit(exitNumber=20B) HTTP/1.1 PATCH /service/road(90)/exit(exitNumber=20B) HTTP/1.1 ``` -#####Bind an entity +##### Bind an entity ```json { "@odata.type":"#Northwind.Manager", @@ -268,14 +268,14 @@ PATCH /service/road(90)/exit(exitNumber=20B) HTTP/1.1 ] } ``` -#####Addressing an Entity Reference +##### Addressing an Entity Reference ```http DELETE /service/Categories(catCode=11)/Products/$ref?$id=../../Products(sku=abc123) DELETE /service/Products(sku=abc123)/Category/$ref ``` -####2.2.3 Key Value Uniqueness +#### 2.2.3 Key Value Uniqueness Alternate Keys are intended to allow callers to refer to a specific entity instance. Therefore, services must allow 1 and only 1 record in an entity collection to match any set of values for the set of properties defined for each key. Services may allow null values in properties that are used for alternate keys, but clients will not be able to retrieve those entities using a key predicate that specifies the null value. A client request that includes a null value for a property in the key predicate MUST return HTTP Status 404 (not found). @@ -287,7 +287,7 @@ http://host/service/persons(ID=null) http://host/service/persons(Country=USA,Passport=null) ``` -####2.2.4 Entity Urls in Service Responses +#### 2.2.4 Entity Urls in Service Responses Support for alternate keys does not imply or require the modification of canonical urls returned by the service that represent links to entities (for example, odata.id, ReadUrl, etc.). Services should continue to return stable references to resources that do not change relative to the access mechanism used by the client to retrieve those references. For Example: @@ -313,4 +313,3 @@ GET /service/Customers(DUNS=987654) HTTP/1.1 "Fax": "030-0076545", } ``` -