From 48329229e3fc0a0e8388896d9cf6508185af0b26 Mon Sep 17 00:00:00 2001 From: Markus Lanthaler Date: Sun, 20 Oct 2013 22:01:23 +0200 Subject: [PATCH 1/2] Make API non-normative --- spec/latest/json-ld-api/index.html | 115 ++++++++++----------------- spec/latest/respec-w3c-extensions.js | 2 +- 2 files changed, 44 insertions(+), 73 deletions(-) diff --git a/spec/latest/json-ld-api/index.html b/spec/latest/json-ld-api/index.html index f9e481271..2d6b8e1a1 100644 --- a/spec/latest/json-ld-api/index.html +++ b/spec/latest/json-ld-api/index.html @@ -104,9 +104,6 @@ border-bottom: 1px dotted #ff4500; text-decoration: none; } - .atrisk-head { - font-style: italic; - } ol.algorithm { counter-reset: numsection; list-style-type: none; @@ -124,10 +121,11 @@
-

This specification defines an Application Programming Interface (API) - and a set of algorithms for programmatic transformations of JSON-LD - documents. Restructuring data according to the defined transformations - often dramatically simplifies its usage.

+

This specification defines a set of algorithms for programmatic transformations + of JSON-LD documents. Restructuring data according to the defined transformations + often dramatically simplifies its usage. Furthermore, this document proposes + an Application Programming Interface (API) for developers implementing the + specified algorithms.

@@ -230,6 +228,7 @@
@@ -237,17 +236,15 @@

Introduction

-

This document is a detailed specification for an Application Programming - Interface for the JSON-LD syntax. The document is primarily intended for - the following audiences:

+

This document is a detailed specification of the JSON-LD processing algorithms. + The document is primarily intended for the following audiences:

To understand the basics in this specification you must first be familiar with @@ -629,24 +626,15 @@

Conformance

MAY, and OPTIONAL in this specification are to be interpreted as described in [[!RFC2119]].

-

There are three classes of products that can claim conformance to this +

There are two classes of products that can claim conformance to this specification: JSON-LD Processors, - JSON-LD API Implementations, and RDF Serializers/Deserializers.

A conforming JSON-LD Processor is a system which can perform the Expansion, Compaction, and Flattening operations defined in this specification.

-

A conforming JSON-LD API Implementation is a conforming JSON-LD Processor - that exposes the Application Programming Interface (API) - defined in this specification. It MUST implement the json-ld-1.0 - processing mode (for further details, see the - processingMode - option of JsonLdOptions).

- -

JSON-LD Processors and - API Implementations MUST NOT +

JSON-LD Processors MUST NOT attempt to correct malformed IRIs or language tags; however, they MAY issue validation warnings. IRIs are not modified other than conversion between relative and @@ -658,8 +646,7 @@

Conformance

defined in this specification.

The algorithms in this specification are generally written with more concern for clarity - than efficiency. Thus, JSON-LD Processors - and API Implementations may + than efficiency. Thus, JSON-LD Processors may implement the algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

@@ -953,7 +940,7 @@

Algorithm

document (which might be different from the currently being processed context), if available; otherwise to null. If set, the base - option of a JSON-LD API Implementation overrides the base IRI. + option of a JSON-LD API Implementation overrides the base IRI.
  • If context is a string,
    1. Set context to the result of resolving value against @@ -3820,54 +3807,39 @@

      Data Round Tripping

    • -
    +

    The Application Programming Interface

    This API provides a clean mechanism that enables developers to convert JSON-LD data into a variety of output formats that are often easier to - work with. A conformant JSON-LD API Implementation MUST - implement the entirety of the following API.

    + work with.

    The JSON-LD API uses Promises to represent the result of the various asynchronous operations. - Promises are defined in - section 4 Promises - of [[!DOM-WHATWG]].

    - -
    -

    Note: This feature is - "at risk" and may - be removed or modified heavily from the feature described in this specification - based on reviewer feedback. Please send feedback to - public-rdf-comments@w3.org. - For the current status see - features "at risk" in JSON-LD 1.0

    -

    The JSON-LD API specification currently only refers to the "Promise" interface and does not attempt to provide any details on the specific implementation of Promises. That is, it does not reference whether or not '.then()' must be specified. This is done in order to allow for some implementation flexibility in the event the DOM Promises spec changes. The editors of the WHATWG DOM specification have asserted that the Promise interface is ready to be incorporated into specifications. The issue relates to how to properly refer to a spec living in the WHATWG as a living standard as well as how to ensure that the interface provided by the spec is stable.

    -
    + Promises are temporarily being drafted on + GitHub + [[!PROMISES]] but are expected to be standardized as part of ECMAScript 6.

    -
    +

    The JsonLdProcessor Interface

    The JsonLdProcessor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods.

    -

    It is important to highlight that conformant - JSON-LD API Implementations - MUST NOT modify the input parameters. If an error is detected, the Promise is +

    It is important to highlight that implementations do not modify the input parameters. + If an error is detected, the Promise is rejected passing a JsonLdError with the corresponding error code and processing is stopped.

    If the documentLoader - option is specified, a conformant JSON-LD Processor MUST use it to dereference remote documents - and contexts. The documentUrl + option is specified, it is used to dereference remote documents and contexts. + The documentUrl in the returned RemoteDocument is used as base IRI and the contextUrl is used instead of looking at the HTTP Link Header directly. For the sake of simplicity, none of the algorithms - in this document mention this directly. JSON-LD API Implementations - are not required to implement the - documentLoader option.

    + in this document mention this directly.

    Promise compact()
    @@ -4080,7 +4052,7 @@

    The JsonLdProcessor Interface

    -
    +

    The JsonLdOptions Type

    The JsonLdOptions type is used to pass various options to the @@ -4097,33 +4069,32 @@

    The JsonLdOptions Type

    LoadDocumentCallback documentLoader = null
    The callback of the loader to be used to retrieve remote documents and contexts. - If specified, it MUST be used to retrieve remote documents and contexts; otherwise, - if not specified, the processor's built-in loader MUST be used.
    + If specified, it is used to retrieve remote documents and contexts; otherwise, + if not specified, the processor's built-in loader is used.
    (object? or DOMString) expandContext = null
    A context that is used to initialize the active context when expanding a document.
    DOMString processingMode = "json-ld-1.0"
    -
    If set to json-ld-1.0, the JSON-LD processor MUST produce +
    If set to json-ld-1.0, the implementation has to produce exactly the same results as the algorithms defined in this specification. If set to another value, the JSON-LD processor is allowed to extend or modify the algorithms defined in this specification to enable application-specific optimizations. The definition of such optimizations is beyond the scope of this specification and thus - not defined. Consequently, different implementations MAY implement - different optimizations. Developers MUST NOT define modes beginning + not defined. Consequently, different implementations may implement + different optimizations. Developers must not define modes beginning with json-ld as they are reserved for future versions of this specification.
    -
    +

    Remote Document and Context Retrieval

    -

    Developers can utilize a callback to control how remote documents and contexts are retrieved - by JSON-LD API Implementations. - This section details the parameters of that callback and the data structure - used to return the retrieved context.

    +

    Users of an API implementation can utilize a callback to control how remote + documents and contexts are retrieved. This section details the parameters of + that callback and the data structure used to return the retrieved context.

    -
    +

    LoadDocumentCallback

    The LoadDocumentCallback defines a callback that custom document loaders @@ -4134,14 +4105,14 @@

    LoadDocumentCallback

    The URL of the remote document or context to load.
    -

    All errors MUST result in the Promise being rejected with +

    All errors result in the Promise being rejected with a JsonLdError whose code is set to loading document failed or multiple context link headers as described in the next section.

    -
    +

    RemoteDocument

    The RemoteDocument type is used by a LoadDocumentCallback @@ -4152,9 +4123,9 @@

    RemoteDocument

    If available, the value of the HTTP Link Header [[!RFC5988]] using the http://www.w3.org/ns/json-ld#context link relation in the response. If the response's content type is application/ld+json, - the HTTP Link Header MUST be ignored. If multiple HTTP Link Headers using + the HTTP Link Header is ignored. If multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context link relation are found, - the Promise of the LoadDocumentCallback MUST be rejected with + the Promise of the LoadDocumentCallback is rejected with a JsonLdError whose code is set to multiple context link headers.
    DOMString documentUrl
    @@ -4167,7 +4138,7 @@

    RemoteDocument

    -
    +

    Error Handling

    This section describes the datatype definitions used within the @@ -4189,7 +4160,7 @@

    JsonLdError

    -
    +

    JsonLdErrorCode

    The JsonLdErrorCode represents the collection of valid JSON-LD error codes.

    diff --git a/spec/latest/respec-w3c-extensions.js b/spec/latest/respec-w3c-extensions.js index b119bf1f7..fa15cfb63 100644 --- a/spec/latest/respec-w3c-extensions.js +++ b/spec/latest/respec-w3c-extensions.js @@ -11,7 +11,7 @@ var localBibliography = { "RFC6906": "Erik Wilde. The 'profile' Link Relation Type. March 2013. Internet RFC 6906. URL: http://www.ietf.org/rfc/rfc6906.txt", "TURTLE": "Eric Prud'hommeaux, Gavin Carothers, Editors. Turtle: Terse RDF Triple Language. 19 February 2013. W3C Candidate Recommendation (work in progress). URL: http://www.w3.org/TR/2013/CR-turtle-20130219/. The latest edition is available at http://www.w3.org/TR/turtle/", "WEBIDL": "Cameron McCormack, Editor. Web IDL. 19 April 2012. W3C Candidate Recommendation (work in progress). URL: http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest edition is available at http://www.w3.org/TR/WebIDL/", - "DOM-WHATWG": "Anne van Kesteren, Aryeh Gregor, Ms2ger, Editors. DOM. September 2013. WHATWG Living Standard (work in progress). URL: http://dom.spec.whatwg.org/", + "PROMISES": "Domenic Denicola. Promise Objects. October 2013. (work in progress). URL: http://www.w3.org/2013/10/json-ld-api/snapshot-promises-draft. The latest draft is available at https://github.com/domenic/promises-unwrapping", "RDF11-MT": "Patrick J. Hayes, Peter F. Patel-Schneider, Editors. RDF 1.1 Semantics. 23 July 2013. W3C Last Call Working Draft (work in progress). URL: http://www.w3.org/TR/2013/WD-rdf11-mt-20130723/. The latest edition is available at http://www.w3.org/TR/rdf11-mt/", "RFC6839": "Tony Hansen, Alexey Melnikov. Additional Media Type Structured Syntax Suffixes. January 2013. Internet RFC 6839. URL: http://www.ietf.org/rfc/rfc6839.txt", }; From db07ff2c9687e8c682a04b7eb0c32668690a6b88 Mon Sep 17 00:00:00 2001 From: Markus Lanthaler Date: Mon, 21 Oct 2013 18:23:50 +0200 Subject: [PATCH 2/2] Make reference to WebIDL non-normative This makes json-ld/json-ld.org#238 moot --- spec/latest/json-ld-api/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/latest/json-ld-api/index.html b/spec/latest/json-ld-api/index.html index 2d6b8e1a1..2b6f19dfb 100644 --- a/spec/latest/json-ld-api/index.html +++ b/spec/latest/json-ld-api/index.html @@ -253,7 +253,7 @@

    Introduction

    of the algorithms in this document. To understand the API and how it is intended to operate in a programming environment, it is useful to have working knowledge of the JavaScript programming language [[ECMA-262]] and - WebIDL [[!WEBIDL]]. To understand how JSON-LD maps to RDF, it is helpful to be + WebIDL [[WEBIDL]]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [[RDF11-CONCEPTS]].