July 22, 2008

BJ

Home, History

Added history page and warning about draft status in first page.

2.X

Responded to some comments.

July 28, 2008

BJ

1 Intro

Added links. Moved terminology to a separate section.

2.2 Single Resource URL

Added comment regarding composite keys (needs review).

2.3 Property URL

Added "Resource Property URL" page (needs review)

2.5 Template URL

Added note on templates being usually readonly

2.8 Query parameters

Modified first example so that both URLs are feeds of the same kind
include=$schema is still under discussion

History

Reformatted as a table

2.9 Query language

Responded to comments

3.3 Field level links

Added hyperlinks to paging section

4.3 XSD structure

Fixed to conform to the convention of appending "Type" to type names

July 29, 2008

BJ

2.1 Collection URL

Clarified syntax when dataset is identified by several parameters

2.2 Single Resource URL

Clarified syntax for composite primary keys

4.X Metadata
11.3 Operation Metadata

Use <xs:all> rather than <xs:sequence> in schemas
Added "SalesOrderLineListType" to 4.1 example and rule on "ListType" in 4.3
Added explanation on how the example is used at the end of page 4.1
Added pluralName SME attribute in 4.1 and 4.3
Added isGlobalId SME attribute in 4.3

3.12 Localization
4.2 SME
2.8 Query Parameters

Added localization page
Added isLocalized SME attribute in 4.3,
Added subsection on localized schemas at the end of 4.3
Added links to localization page in 2.8 and 4.3

12.X

Promoted batch section from staging to live

July 30, 2008

BJ

3.5 SLE

Added Simple List Extensions page
Renumbered sections 3.X that follow (renumbered them also in history).
Fixed reference to SLE in 4.2 Simple Metadata Extensions.

3.8 Linking and Embedding

Created a subsection to describe how related resources are linked/embedded.
Renumbered sections 3.X that follow (also in history).
Trimmed 6.5 (Controlling the Payload) because the linking/embedding
explanations are now in 3.8.

July 31, 2008

BJ

4.X Metadata

Revamped the whole metadata section
Added Resource Kind Definition page as 4.2
Added Property Definition page as 4.3
Added Relationship Definition page as 4.4
Added Service Operation Definition page as 4.5
Added Auxiliary Type Definitions page as 4.6
Old 4.2 (SME) has become 4.7 and is now only a summary
Old 4.3 (XSD structure) has become 4.8 and has been trimmed down
(details are in the new sections) 
Introduced a new SLE attribute: path.

5.X Security

Reviewed the security section
Removed Single Sign-On from the menu and intro page (no specs yet)
Only cosmetic changes to 5.1 and 5.2

Aug 1, 2008

BJ

6.X Queries

Reviewed the query section.
Added content in 6 Queries (intro page)
Added example response in 6.1 Example (was only referencing 3.1 before)
Added a suggestion to introduce a pagingMode SME attribute in 6.4 Paging
Rest is cosmetic.

Aug 4, 2008

BJ

6.7 Feed Rendering

Added content for this page

6.9 Error Handling

Reviewed. Added links on codes.
Added Retry-After recommendation on 503 and responded to comment.

7.X Read Operation

Reviewed the read section.
Added content in 7 Read (intro page)
Added specific error handling content (was a reference to query EH section before).
Rest is cosmetic.

6.8 Queries on Property URLs

Added this page.
Query Error Handling page is now 6.9 (also in history).

Aug 5, 2008

BJ

7.4 Read on Property URLs

Added this page.
Read Error Handling page is now 7.5 (also in history).
Proposed to add a cardinality SME attribute (needs WG review).

8.X Create Operation

Reviewed the create section
Added content in 8 Create (intro page)
Added ETag header to example response in 8.1
Added response example in 8.2 $template URL
Added 8.3 Creating Child Resources (renumbered following subsections)

4.X Metadata
6.8 Queries on Property URLs
7.4 Read on Property URLs
8.3 Creating Child Resources

Extended the use of canGet, canPost, canPut and canDelete SME attributes
to relationship properties
Also, moved name and type attributes before sme attributes in schema examples(more logical and easier to read).

9.X Update Operation

Reviewed the update section
Added content in 8 Update (intro page)
Added 9.2 Partial Update (needs WG review)
Added 9.4 Update on a Property URL (no content yet)
Renumbered sections 9.2 and above.
Rest is cosmetic. Concurrency handling section not reviewed yet.

Aug 6, 2008

BJ

6.X, 7.X, 8.X, 9.X, 10.X

Reviewed page titles.
Added Query/Read/Update/Delete so that user sees immediately which operation is described.

9.3 Update Concurrency Handling
3.11 SData Atom Extensions
9.5 Update Error Handling

Rewrote concurrency handling section.
Removed <sdata:etag> in PUT entry (it is now <sdata:ifMatch> and is only required in batch mode).
Added ifMatch to the SData Atom Extensions
Removed 409 entry in error handling table
(WG decision was to return 400 rather than 409 when If-Match is missing).

9.4 Update on Property URL

Added 9.4 Update on Property URL section (renumbered afterwards)

10.X Delete Operation

Reviewed the delete section
Added content in 10 Delete (intro page)
Rewrote 10.2 Concurrency Handling section
Added 10.3 Delete on Property URL section (renumbered afterwards)
Reviewed 10.4 Error Handling section (removed 409 table entry)

11.X Service Operations

Reviewed the service operations section
Added content in 11 Service Operation (intro page)
Added path attribute in 11.3 Operation Metadata section.
Rest is cosmetic

12.X Batch Operations

Reviewed the batch operations section
Added content in 12 Batch Operations (intro page)
Changed <sdata:etag> to <sdata:ifMatch> in PUT batch entries.
Added 12.6 Batch Error Handling section.
Rest is cosmetic.

2.11 Resource Versioning
3.1 Feed Example
3.3 Feed Links 
2.6 Schema URL

Added 2.11 Resource Versioning section
Modified 3.1 and 3.2 feed example to include a version parameter in schema link.
Also added version parameter in 2.6 Schema URL example.

4.9 Inlined Schemas
2.8 Query Parameters
4 Metadata

Added 4.9 Inlined Schemas section.
Added includeSchema parameter in 2.8 Query Parameters
Added link to new section in 4 Metadata intro page.

Aug 7, 2008

BJ

6.4 Query Paging
4.2 Resource Kind Definition
4.4 Relationship Definition
4.7 SME Summary

Added sme:pagingModes attribute

Home page
1 Introduction

Added warning to inform that the standards documents are not yet available.

Aug 8, 2008

BJ

All pages that contain
XSD or XML examples

Passed all the examples through strict XML validation.
Detected glitches and fixed them. Main ones are:
<schema> element was lacking elementFormDefault="qualified" attribute
Schema example did not have definitions for uuid properties
Schema example was lacking minOccurs="0"
Some <feed> and <entry> elements were lacking xmlns attributes.
<orderDate> and <shipDate> elements were incorrectly formatted.

3.13 SData Atom Extensions

location element was lacking in the table (schema validation pass detected it)

9.2 Partial Updates

Recommend that minOccurs be explicitly set to 0 (I was wrong in assuming that 0 was the default value)

Appendix A: sme.xsd
Appendix B: sdata.xsd
3.13 SData Atom Extensions
4.7 SME Summary

Added appendices. The schemas are the ones I used to validate the examples.
Added a link to the corresponding appendix at the end of 3.11 and 4.7

Aug 12, 2008

BJ

4.1 Typical SData Schema
4.2 Resource Kind Definition
4.3 Property Definition
4.4 Relationship Definitions
4.7 Simple Metadata Extensions Summary
4.9 Inlined Schemas
6.4 Query Paging
6.7 Feed Rendering
12.2 Metadata Extension for Batching
Appendix A: sme.xsd

Replaced pagingModes attribute by separate canPageXxx attributes

Replaced roles attribute by separate isIdentifier and isDescriptor attributes

2.4 Service Operation URL

Only allow $service after contract URL and resource kind URLs

3.11 Tracking Payload
11.5 Asynchronous Operations
12.5 Asynchronous Batch Operations
Appendix B: sdata.xsd

elapsedTime -> elapsedSeconds
remainingTime -> remainingSeconds

Aug 13, 2008

BJ

2.3 Resource Property URL
4.1 Typical SData Schema
4.2 Resource Kind Definition
4.3 Property Definition
4.4 Relationship Definitions
4.7 Simple Metadata Extensions Summary
8.3 Create on Property URL
Appendix A: sme.xsd

Added sme:isReadOnly and sme:isCollection attributes

Aug 19, 2008

BJ

All feed or entry examples
Appendix C: sdatahttp.xsd

Split sdata namespace in two
(elements that mirror HTTP headers are in separate namespace).

All feed or entry examples
3.3 Feed-level links

Added linkRel/#post link
fixed typos in linkRel rel attributes.

2.8 Intermediate URLs
3.4 Categories
3.12 SData Category Scheme
6.9 Query on intermediate URL
3.X examples

Added these pages to describe how intermediate URLs are handled.
Also introduced categories and the SData category scheme.
The examples of section 3 have been updated with categories.
Examples in the other sections have not yet been updated (will be tomorrow).

Aug 20, 2008

BJ

3.3 Feed-level links
All feed or entry examples

Fixed SData URL for link relations (http:// prefix added, linkRel -> link-relations, 2008/1/ removed).
Added link-relations/service to have a link to the $service URL.
Introduced <category> element in all examples

9.2 Partial Updates

Modified the "Schema Implications" subsection to indicate that a given contract can impose full payloads on updates by setting minOccurs to 1. 

History of Changes

Added hyperlinks to the modified sections (only last entries)

Aug 22, 2008

BJ

Appendix D: categories.xml
3.12 SData Category Scheme

Added Atom Category Document for the SData category scheme.

13.X Synchronization

Renamed sequence -> tick

Oct 6, 2008

BJ

Whole wiki

Cleaned up comments. Saved old comments in a file.

3.11 Tracking Payload
Appendix B: sdata.xsd
Misc examples

Added <pollingMillis> element to tracking payload

4.2 Resource Kind Definition
4.3 Property Definition
11.3 Operation Metadata
Appendix A: sme.xsd

Added "unsupported" SME attribute

4.X Metadata
11.3 Operation Metadata

Changed complexType suffixes.
XxxType -> Xxx--type
XxxListType -> Xxx--list

4.7 Simple Metadata Extensions Summary
Appendix A: sme.xsd

Added full-text search feature:
search query parameter
canSearch SME attribute

Oct 7, 2008

BJ

3.1 Typical Feed
3.8 Resource Payload
Appendix B: sdata.xsd
All examples containing paylaod

Added <sdata:payload> element around payload.

!!! THIS IS A BREAKING CHANGE !!!

Added impersonation section (SSO proposal for CRM/ERP)
Only in STAGING for now.

Oct 13, 2008

BJ

Added diagram and improved example

Oct 14, 2008

BJ

Added CAS SSO section (alternate SSO proposal for CRM/ERP and Orion)
Only in STAGING for now.

Oct 30, 2008

BJ

13.1.3 UUID Domains
13.1.4 Protocol Elements for Linking

Completed the linking section (STAGING only)

Nov 17, 2008

BJ

Added a proposal for conformance levels

Nov 24, 2008

BJ

2.6 Resource Schema URL
2.7 System URL
2.9 Query Parameters
2.10 Query Language
3.3 Feed-level Links
3.10 Error Payload
3.13 SData Atom Extensions
4 Metadata
5.2 Authentication
6.5 Query Payload Control
6.10 Query Error Handling
7.1 Read Example
10.2 Delete Concurrency Handling
11.3 Operation Metadata
Appendix A
Appendix B

Reviewed comments. Following points need review by WG:
2.6 Schema fragment. If agreed, I'll add id attribute to schema examples.
2.7 Need to decide how we handle the SData registry.
2.10 Conformance levels for query language.
3.3 Settle status of post link
3.10 Complete list of error codes.
3.13 Decide on SData namespace
6.5 Review depth issue.
6.10 Need agreement on 500 vs 503.
10.2 Relevance of ETag for delete.
11.3 Introduction of batchingMode.

Other issues:
- Do we need to introduce JSON format now?
- Need section on X-HTTP-Method-Override

Jan 12, 2009

BJ
Karen

All

New URL syntax for dataset component

Jan 19, 2009

BJ

9.1 Update Example
10.1 Delete Example

Added note about X-HTTP-Method-Override header

Mar 16, 2009

BJ

Rewrote SSO proposal

Mar 20, 2009

BJ

Completed in depth review of Link&Sync section

Mar 31, 2009

BJ

Simplified synchronization feed to use one digest instead of two. Floor and ceiling digests don't exist any more.
Introduced <syncMode> element to distinguish between catch up and immediate sync.

Apr 1, 2009

BJ

Added case sensitivity rules for URL syntax

Apr 6, 2009

BJ

3.14 Localization
4.1 Typical SData Schema
4.8 Schema Rules
12.3 Synchronous Batch Request
2.10 Query Language

Fixed points submitted by Nathan Baulch on forum.

Apr 7, 2009

BJ

Fixed typo. Removed "envelope" attribute which was a leftover from a previous version of the specs.

Apr 20, 2009

BJ

Added SData registry pages

Jul 12, 2009

BJ

Misc pages

Fixed typos found by Nathan Bauch

Jul 13, 2009

BJ

Added select query parameter

Jul 13, 2009

BJ

2.9 Query Parameters
8.1 Create Example
9.2 Partial Updates

Added returnDelta query parameter

Jul 13, 2009

BJ

Added section on URL extensibility

July 13, 2009

BJ

11.3 Operation Metadata
4.7 Simple Metadata Extensions Summary

Added section on $template URL for service operations

July 16, 2009

BJ

12 Named Queries
2.5 Named Query URL

Added named query section

4.7 Simple Metadata Extensions Summary
+ misc other pages

sme:mandatory has been renamed sme:isMandatory

Added <properties> element to registry endpoints (simple extensibility mechanism).

July 17, 2009

BJ

Appendix D: categories.xml

Added intermediate URLs and categories for named queries

Added registry.xsd appendix

July 20, 2009

BJ

Appendix B: sdata.xsd

Inlined schema are now inside <sdata:schema> element, instead of <atom:link> element.

Added section on schema import and include.

Allow trackingID on regular POST operations.

Added section to describe encoding of non ASCII characters in URLs

Added versions summary page

July 21, 2009

BJ

Appendix B: sdata.xsd

Introduced sdata attributes for resource linking (url, key, uuid)

Wrote section on relationship handling in sync.

July 22, 2009

Added sme:maxLength and sme:averageLength attributes

11.5 Asynchronous Operations

Removed synchronous mode for reliable posting (was problematic)
Added note about potential synchronous handling of asynchronous service operations

Added text to clarify the distinction between parent/child relationships and associations

Added includeUuid and includePayload parameters (used by linking protocol).

Added syntax with additional fragment, for imported/included schemas

Added page on miscellaneous URLs to cope with $post tracking URL

July 23, 2009

BJ

Added JSON mapping

2.10 Query Parameters

Added * wildcard to select syntax.

Added Atom <author> element to make SData feed conformant with Atom.

Added sdata:lookup as optional attribute to payload reference

Reviewed metadata section. Got rid of the "ID" elements in the example as this information is now carried via sdata:key attributes.

July 24, 2009

Added example of select parameter
Changed select syntax to use / rather than . for consistency with include.

Modified to direct people to use sdata:url rather than <link> elements to navigate through the data.

Chapters 6 to 13

Did a general pass to modify all the examples so that they use the new sdata:uuid/key/url attributes instead of <id> or <uuid> property elements.
Fixed some typos too.

Aug 17, 2009

BJ

14.5.2 Querying Source Synchronization Feed
14.5.8 Immediate Synchronization

Replaced <sync:uuid> element by sdata:uuid attribute in sync feed examples.
Got rid of <http:httpMethod> as sync action is now carried by sdata:isDeleted attribute.

Aug 21, 2009

BJ

2.11 Query Parameters

Simplified the linking protocol. The includeUuid and includePayload query parameters have been eliminated.

Sep 2, 2009

BJ

3.13 SData Atom Extensions
Appendix B: sdata.xsd

Deprecated the <link rel="related"> mechanism to represent links between resources.

Removed sdata:payloadPath attribute from 3.13 and Appendix A.

Added --enum convention for enumerated types.

Sections 1 to 6 (included)

First pass on MUST/SHOULD/MAY language

Sep 3, 2009

BJ

4.2 Resource Kind Definition
4.7 Simple Metadata
Extensions Summary
Appendix A: sme.xsd

Added sme:hasUuid attribute

Relaxed the checking rules on delete with etags.

Sep 16, 2009

BJ

Sections 7 to 12 (included)

Added MUST/SHOULD/MAY language and compliance paragraphs

Sep 18, 2009

BJ

Section 13 (batching)

Added MUST/SHOULD/MAY language and compliance paragraphs

3.13 SData Atom Extensions
6.5 Query Payload Control
Appendix B: sdata.xsd

Added include=$descriptors query parameter and sdata:descriptor attribute.

Appendix A: sme.xsd

Added sme:totalDigits and sme:fractionDigits attributes.
Added maxLength and averageLength attributes to sme.xsd (they were missing).

Sep 28, 2009

BJ

Replaced current SSO proposal by a statement about SData supporting the upcoming SSO protocol.

3.13 SData Atom Extensions
6.5 Query Payload Control
Appendix B: sdata.xsd

Modified the update protocol for child resources. Made it consistent with the sync protocol.
Introduced sdata:deleteMissing flag to allow legacy (0.9) providers to support both protocols.

BJ

Hid JSON page as it is not ready for prime time.

Sep 30, 2009

BJ

Various pages

Fixed typos spotted by Bill Medlands

Clarified the description of itemsPerPage

Converted the FIXME paragraph about the incomplete list of error codes into a warning, with a different wording.

Added an example with a list of criteria.
Added a compliance statement for the support of multiple criteria.

Fixed the rule for <progress> values (they MAY decrease now).

Improved description of sdata url, key, uuid, descriptor and lookup attributes

Oct 1, 2009

BJ

Clarified the rules for multiple criteria

Clarified who is responsible for percent encoding non ASCII characters in URLs.

Fixed inconsistent MUST / SHOULD NOT combination in the paragraph that says that the consumer MUST NOT build the tracking URL itself.

Oct 5, 2009

BJ

Various pages

Fixed typos reported by Nathan Baulch.

Oct 9, 2009

BJ

Appendix A: sme.xsd

Brought SME wiki page and appendix in sync with gforge xsd file

Oct 12, 2009

BJ

Added compliance summary page.

Appendix B: sdata.xsd

Brought SME wiki page and appendix in sync with gforge xsd file

Synchronization pages

Flattened the structure.
Moved sync sections one level up in the hierarchy. Got rid of 3 digit section numbers.

All pages with examples

Renamed the example URL segments: sageApp/test -> myApp/myContract
Renamed the example schema namespace: demoErp -> myContract

Oct 16, 2009

New page for Postel's Law (not yet in navigation tree)

3.2 Feed Elements

Added optional processing instruction at the top of the example feed.

Oct 21, 2009

BJ

Navigation tree

Enabled General Principles page in navigation tree

Oct 29, 2009

BJ

Fixed error in definition of sme:path (it is relative to dataset segment, not contract segment).

Nov 2, 2009

BJ

and following pages.

Added dataset segment to URLs (/-/), so that registry URLs have the same structure as other contract URLs.

Synchronization protocol

Added runName and runStamp parameters

Nov 26, 2009

BJ

14.3 Endpoint Resource

Fixed typo: /sdata component was missing from URLs.

Dec 23, 2010

BJ

9 Update Operation
9.2 Update Payloads
Appendix B: sdata.xsd

Changed the title of 9.2: Partial Updates --> Update Payloads
Rewrote and expanded 9.2 section on child resources:

• Distinguished single resource, list of children, reference and association cases.
• sdata:deleteMissing is not a compatibilty mode any more, but a primary update mode for lists.

Note: also added sdata:index as "reserved for future use" in sdata.xsd

4.3 Property Definition
4.7 Simple Metadata Extensions
Summary
11.3 Operation Metadata
Appendix A: sme.xsd

Added sme:tags and sme:syncOrder

2.11 Query Parameters
2.14 Resource Versioning
4.1 Typical SData Schema
4.8 Schema Rules

Added schema version. Main description is in 4.8 Schema Rules

Synchronization Protocol
2.2 Tick Management
4.2 Synchronization Digest
4.4 Synchronization Feed
4.5 Synchronization Metadata

Clarified tick management: tick must increase in a sync feed (rule was already at the end of 4.4 but 2.2 was evasive).
Added a table with recommended conflict priority values (1, 5, 9) in 4.2
Added a statement that payload MUST be complete in 4.4
Added sme:syncConflictPriority and sme:syncOrder to 4.5

Jan 21, 2011

BJ

Clarified description of delete on associations

4.3 Property Definition
4.7 Polymophic relations

Added caveat that sme:tags should be not be used as a replacement for existing SME attributes, but only as an extension mechanism

Synchronization Protocol
4.5 Synchronization Metadata

Simplified description of conflict priority range

Synchronization Protocol (all pages)

Added compliance paragraphs

Jan 24, 2011

BJ

Added section on polymorphic relations.
Renumbered 4.x sections with x >=7

Synchronization Protocol
4.2 Synchronization Digest
4.3 Per-resource Synchronization State

Added data types in tables

Synchronization Protocol
Appendix A: sdatasync.xsd

Added appendix A

Jan 27, 2011

BJ

Added isDeleted flag which was missing in XSD file.

Added examples of payloads for polymorphic relations

Feb 7, 2011

BJ

4.2 Resource Kind Definition
4.8 Simple Metadata Extensions Summary
Appendix A: sme.xsd

Added protocol filter variables

Synchronization Protocol
4.3 Per-resource Synchronization State
Appendix A: sdatasync.xsd

Added <user> element to <syncState>

Feb 9, 2011

BJ

12.3 Named Query Metadata

Documented usage of where, orderBy, include, select in named queries

Feb 21, 2011

BJ

Synchronization Prototocol
4.4 Synchronization Feed

Relaxed requirement on children list in sync. sdata:deleteMissing=true is not mandated any more but list must still include all elements.

Feb 25, 2011

BJ

Synchronization Prototocol
Appendix A: sdatasync.xsd

Fixed missing <syncMode> element in schema