JSON-LD Features at Risk

These features of JSON-LD 1.0 were marked "at risk" in a published JSON-LD 1.0 specification. This means that the Working Group identified them as features which might be removed in the future, based on new information (including a lack of evidence of implementations), as described in the W3C Process Document.

@base keyword

Support for the @base keyword might be removed from JSON-LD 1.0 if implementation experience reveals that the fact that a document may have multiple base IRIs is confusing for developers. It is also being discussed whether relative IRIs are allowed as values of @base or whether the empty string should be used to explicitly specify that there isn't a base IRI, which could be used to ensure that relative IRIs remain relative when expanding.

In the 11 April 2013 LC WDs: json-ld and json-ld-api

Resolution: Relative IRIs are allowed us values of @base. The empty string is interpreted as a relative IRI. Setting @base to null to specify that there is no base IRI.

See also https://github.com/json-ld/json-ld.org/issues/223

Reverse properties

Reverse properties might be removed from JSON-LD 1.0 if implementation experience reveals problems with supporting this feature.

In the 11 April 2013 LC WDs: json-ld and json-ld-api
In the 16 May 2013 LC2 WD: json-ld-api

Resolution: Support reverse properties in JSON-LD 1.0.

Allow blank nodes to be used as graph name or property

RDF does not currently allow a blank node to be used as graph name or property, while JSON-LD does. JSON-LD-RDF Converters can work around this restriction, when converting JSON-LD to RDF, by converting such blank nodes to IRIs, minting new "Skolem IRIs" as per Replacing Blank Nodes with IRIs of [RDF11-CONCEPTS]. Based on feedback from implementors the Working Group may decide to disallow blank nodes as graph names and properties in JSON-LD. If this change would affect you, be sure to send in a comment.

In the 11 April 2013 LC WDs: json-ld and json-ld-api
In the 16 May 2013 LC2 WD: json-ld-api

RDF has been updated to allow blank nodes to be used as graph name.

Resolution: Allow blank nodes to be used as graph name or property.

Converting list of lists to JSON-LD

In the interest of space and simplicity, the steps necessary for handling lists of lists have been omitted. Such lists and their elements must, recursively, be handled like other lists. Lists of lists can, however, not be represented in JSON-LD using @list; they have to be represented as a set of interlinked node objects using RDF's rdf:first and rdf:rest properties. The Working Group might either require handling of lists-of-lists or forbid them in JSON-LD 1.0. Implementers please send reports of whether you are able to implement handling for lists-of-lists or would instead request such structures be disallowed.

In the 11 April 2013 LC WD: json-ld-api In the 16 May 2013 LC2 WD: json-ld-api

Resolution: The algorithm was updated to convert lists of lists to expanded form, i.e., list nodes linked together by rdf:rest properties. The @list keyword does not support list of lists.

The JSON-LD algorithms have been updated to support conversion of lists of lists to list objects by preserving the blank node head of the inner list. Lists of lists can, however, not be represented directly in JSON-LD using the @list construct; they have to be represented as a set of interlinked node objects using RDF's rdf:first and rdf:rest properties. Implementors are asked to pay particular attention to the feature and provide feedback on lists of lists and partial lists. The feature may remain in the specification, or it may be removed after further implementation experience has been gathered. Similarly, partial list conversion in the RDF algorithms have been marked as a feature at risk and may be removed from the specification based on implementation feedback.

In the 22 August 2013 CR: json-ld-api

Resolution: Support conversion of lists of lists to list objects by preserving the blank node head of the inner list.

Use of method overloading to make the options parameter optional

The definition of the JsonLdProcessor interface uses method overloading to make the "options" parameter optional. According to the current version of the Web IDL specification [WEBIDL], this would not be supported as the "options" parameter (a dictionary) and the callback parameter (a callback function) are not distinguishable. A bug report has been already been filed. If it turns out that this is not a bug, the Working Group may change the interface by swapping the "options" and "callback" parameter.

In the 11 April 2013 LC WD: json-ld-api

Resolution: The API has been updated to use Futures instead of callbacks which means that method overloading is not needed anymore as the callback parameter was eliminated.

See also https://github.com/json-ld/json-ld.org/issues/238 and https://github.com/json-ld/json-ld.org/issues/240

Default value of base member in JsonLdOptions

The default value of base in JsonLdOptions implies that all IRIs that cannot be compacted otherwise are transformed to relative IRIs during compaction. To avoid that data is being lost, developers thus have to store the base IRI along with the compacted document. Based on implementer feedback, the Working Group may decide to change the default value to null, meaning that IRIs are not automatically compacted to relative IRIs.

In the 11 April 2013 LC WD: json-ld-api

Resolution: The base member of JsonLdOptions has no default value. It is only taken into consideration if it was set explicitly.

See also https://github.com/json-ld/json-ld.org/issues/223

Conversion to/from JSON Native Types

JSON-LD-API allows certain RDF literals to be mapped to JSON numbers (if the "use native types" flag is set). The mapping rules

are currently being debated as is which JSON-LD API methods the "use native types" will have an effect in. There may be changes made to the

algorithm and API based on feedback during the Last Call. Implementers and reviewers should keep a close eye on the details for this mechanism.

In the 16 May 2013 LC2 WD: json-ld-api

Resolution: The default value of the useNativeTypes flag is set to 'false' in the JSON-LD API. Explanatory text is added to the JSON-LD API specification explaining the risks of the useNativeTypes flag and how to do proper conversion to/from native types using the to/from RDF method call.

See also: http://www.w3.org/2011/rdf-wg/track/issues/129

Properly referencing the DOM Futures spec

The JSON-LD API specification currently only refers to the "Future" interface and does not attempt to provide any details on the specific implementation of Futures. 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 Futures spec changes (which the editors of the specification have asserted that the 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.

In the 16 May 2013 LC2 WD: json-ld-api

See also: http://www.w3.org/2011/rdf-wg/track/issues/130 and http://lists.w3.org/Archives/Public/public-rdf-wg/2013May/0260.html

Resolution: Make the JSON-LD WebIDL API non-normative and refer to the Promises specification written by Domenic Denicola and proceed straight to Proposed Recommendation.

Confusion related to context-sensitivity of @type

A number of JSON-LD document authors have been confused with the context sensitivity of @type. When used in the context, it means "coerce the string value associated with the term to the following datatype." When used in the body of a document in a JSON-LD object that represents a node in the graph, it means "the rdf:type of the subject identified by @id is the one that is the value associated with the @type keyword". When used in expanded literal form, it means "the datatype of the value associated with @value is the value associated with the @type keyword". This shifting of usage has led to confusion that may be easily remedied by reading a tutorial or the specification. It may also be that further modifications for declaring a datatype may be required, such as introducing a "@coerce" or "@literalType" keyword.

In the 22 Aug 2013 CR WD: json-ld

Resolution: Make an editorial update to the JSON-LD specification to clarify that the @type keyword is context sensitive and make its various usages more clear in the specification.

Support for @base: null

Unlike many other serialization formats, JSON-LD allows to specify that there is no base IRI from within the document (by setting @base to null). The result is that the algorithm for establishing a base IRI as specified in RFC3986 section 5.1 is overridden so relative IRIs remain relative IRIs even in the case that an IRI would be available in one of the outer layers (e.g., the IRI used to retrieve the document or an application supplied base IRI). Based on implementer feedback, the Working Group may decide to remove this feature from JSON-LD 1.0.

In the 22 Aug 2013 CR WD: json-ld json-ld-api

Resolution: Keep the @base: null feature in the JSON-LD specification as it is defined in the Candidate Recommendation specification.