Skip to content
This repository has been archived by the owner on Sep 23, 2024. It is now read-only.

Fixup markdown in OData.Community.Keys.V1.md to display properly #25

Merged
merged 1 commit into from
Jan 29, 2020
Merged

Fixup markdown in OData.Community.Keys.V1.md to display properly #25

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 23 additions & 24 deletions OData.Community.Keys.V1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -100,7 +100,7 @@ The following metadata described a Person entity type with an alternate key on t
</EntityType>
```

####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
Expand Down Expand Up @@ -132,7 +132,7 @@ The following metadata described a Person entity type with an alternate key defi
</EntityType>
```

####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
Expand Down Expand Up @@ -167,7 +167,7 @@ The following metadata described a Person entity type with an alternate key defi
</EntityType>
```

####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
Expand Down Expand Up @@ -205,7 +205,7 @@ The following metadata described a Person entity type with two alternate key def
</EntityType>
```

####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.
Expand All @@ -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
Expand All @@ -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",
Expand All @@ -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).
Expand All @@ -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:
Expand All @@ -313,4 +313,3 @@ GET /service/Customers(DUNS=987654) HTTP/1.1
"Fax": "030-0076545",
}
```