From c1188c74a8eccddc0d3ec3caf693531fb45b0465 Mon Sep 17 00:00:00 2001 From: Carlo van Driesten Date: Thu, 10 Sep 2026 21:04:32 +0200 Subject: [PATCH] docs: pin standards references and define conformance scope Signed-off-by: jdsika --- README.md | 10 +- docs/api.md | 50 +- docs/standards/README.md | 137 + docs/standards/manifest.json | 426 + docs/standards/references/.gitattributes | 1 + .../references/ietf-license-info.html | 352 + docs/standards/references/ietf-tlp-5.html | 376 + docs/standards/references/json-ld11-api.html | 8498 ++++++++++ docs/standards/references/json-ld11.html | 13368 ++++++++++++++++ docs/standards/references/n-quads.html | 796 + docs/standards/references/n-triples.html | 833 + docs/standards/references/rdf-canon.html | 6218 +++++++ .../references/rdf-syntax-grammar.html | 4193 +++++ docs/standards/references/rdf11-concepts.html | 1655 ++ docs/standards/references/rfc3667.txt | 1011 ++ docs/standards/references/rfc3986.txt | 3419 ++++ docs/standards/references/rfc3987.txt | 2579 +++ docs/standards/references/rfc8259.txt | 899 ++ docs/standards/references/trig.html | 1515 ++ docs/standards/references/turtle.html | 1950 +++ .../references/w3c-document-license-2002.html | 389 + .../references/w3c-document-license.html | 389 + .../w3c-software-document-2015.html | 389 + .../w3c-software-document-2023.html | 389 + docs/standards/references/xml-names.html | 925 ++ docs/standards/references/xml.html | 2215 +++ pyproject.toml | 1 + scripts/check_standards.py | 231 + src/diffable_rdf/__init__.py | 4 +- src/diffable_rdf/canonicalize.py | 10 +- src/diffable_rdf/jsonld.py | 10 +- src/diffable_rdf/turtle.py | 22 +- src/diffable_rdf/wl.py | 2 +- tests/README.md | 12 + tests/standards/test_references.py | 250 + 35 files changed, 53489 insertions(+), 35 deletions(-) create mode 100644 docs/standards/README.md create mode 100644 docs/standards/manifest.json create mode 100644 docs/standards/references/.gitattributes create mode 100644 docs/standards/references/ietf-license-info.html create mode 100644 docs/standards/references/ietf-tlp-5.html create mode 100644 docs/standards/references/json-ld11-api.html create mode 100644 docs/standards/references/json-ld11.html create mode 100644 docs/standards/references/n-quads.html create mode 100644 docs/standards/references/n-triples.html create mode 100644 docs/standards/references/rdf-canon.html create mode 100644 docs/standards/references/rdf-syntax-grammar.html create mode 100644 docs/standards/references/rdf11-concepts.html create mode 100644 docs/standards/references/rfc3667.txt create mode 100644 docs/standards/references/rfc3986.txt create mode 100644 docs/standards/references/rfc3987.txt create mode 100644 docs/standards/references/rfc8259.txt create mode 100644 docs/standards/references/trig.html create mode 100644 docs/standards/references/turtle.html create mode 100644 docs/standards/references/w3c-document-license-2002.html create mode 100644 docs/standards/references/w3c-document-license.html create mode 100644 docs/standards/references/w3c-software-document-2015.html create mode 100644 docs/standards/references/w3c-software-document-2023.html create mode 100644 docs/standards/references/xml-names.html create mode 100644 docs/standards/references/xml.html create mode 100644 scripts/check_standards.py create mode 100644 tests/standards/test_references.py diff --git a/README.md b/README.md index 2a4c1c4..2f07eab 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ blank-node churn. RDF serializers number blank nodes (`_:c14nN`, `_:Nb1e2…`) in a process-dependent order, so regenerating a file can rewrite most of it even when nothing semantically changed. `diffable-rdf` canonicalizes the graph with -[RDFC-1.0](https://www.w3.org/TR/rdf-canon/), replaces the canonical sequential +[RDFC-1.0](https://www.w3.org/TR/2024/REC-rdf-canon-20240521/), replaces the canonical sequential labels with Weisfeiler-Lehman structural hashes that depend only on each blank node's neighbourhood, and re-serializes through rdflib for idiomatic output. Every triple is preserved; only syntactic form changes. @@ -56,7 +56,7 @@ in another order, or with the blank nodes renamed — produces the same bytes. | Function | Use it for | |---|---| | `deterministic_turtle(graph)` | Diff-stable, idiomatic Turtle. The default choice for files kept in version control. | -| `canonicalize_rdf_graph(graph, output_format="turtle")` | A canonical form in another format: N-Triples, N-Quads, RDF/XML, TriG, N3, JSON-LD. Its Turtle is laid out differently from `deterministic_turtle`'s — same terms, different presentation. | +| `canonicalize_rdf_graph(graph, output_format="turtle")` | Deterministic serialization using RDFC-1.0 blank-node labels: N-Triples, N-Quads, RDF/XML, TriG, N3, JSON-LD. Its Turtle is laid out differently from `deterministic_turtle`'s — same terms, different presentation. | | `deterministic_json(obj)` | Ordering an existing JSON or JSON-LD document, without touching RDF. | | `well_known_prefix_map()` | Normalizing prefix aliases (`sdo` → `schema`) to rdflib's curated names. | | `wl_blank_node_labels(quads)` | Diff-stable labels for blank nodes in quads you have already canonicalized. | @@ -67,6 +67,12 @@ Full signatures, error cases and per-format behavior are in the Changes that affect the bytes this library emits are listed in the [changelog](https://github.com/ASCS-eV/diffable-rdf/blob/main/CHANGELOG.md). +The [standards profile and pinned originals](https://github.com/ASCS-eV/diffable-rdf/blob/main/docs/standards/README.md) distinguish +RDF term fidelity from project-specific presentation. These graph serializers +use the dependency's RDFC-1.0 labeling algorithm; their output is not advertised +as standardized canonical N-Quads bytes or a standalone RDFC processor interface. +WL labels and JSON ordering are project features, not additional RDF standards. + ## Limits worth knowing before you start - **One graph at a time.** The graph serializers take an `rdflib.Graph` and diff --git a/docs/api.md b/docs/api.md index 1402e16..becf8af 100644 --- a/docs/api.md +++ b/docs/api.md @@ -22,7 +22,7 @@ sample data. ## Contents - [`deterministic_turtle`](#deterministic_turtle) — diff-stable Turtle -- [`canonicalize_rdf_graph`](#canonicalize_rdf_graph) — canonical form in other formats +- [`canonicalize_rdf_graph`](#canonicalize_rdf_graph) — deterministic serialization in other formats - [`deterministic_json`](#deterministic_json) — ordering a JSON or JSON-LD document - [`well_known_prefix_map`](#well_known_prefix_map) — namespace IRI to standard prefix - [`wl_blank_node_labels`](#wl_blank_node_labels) — diff-stable labels for canonical quads @@ -49,11 +49,14 @@ named-node IRIs; re-serialization through rdflib's Turtle writer, which recovers inline blank nodes `[ … ]`, collection syntax `( … )` and prefix declarations limited to the namespaces the graph uses. -The rendered text is re-parsed and compared with the input as RDFC-1.0 -canonical forms. RDFC-1.0 ([RDF Dataset Canonicalization][rdfc], a W3C -Recommendation of 21 May 2024) produces one canonical form per isomorphism -class, so comparing those forms is an exact isomorphism test in the sense of -[RDF 1.1 Concepts §3.6][concepts]. Turtle's `( … )` syntax can only +The rendered text is re-parsed and compared with the input using sorted RDF +term strings after pyoxigraph's RDFC-1.0 labeling. This internal comparison +key tests graph isomorphism in the sense of +[RDF 1.1 Concepts §3.6][graph-comparison]; it is not the standardized +canonical N-Quads byte representation. The WL-relabelled Turtle output is +project-specific presentation, not RDFC canonical bytes. See the +[standards profile](standards/README.md) and [RDFC §2][rdfc-conformance]. +Turtle's `( … )` syntax can only express a list whose tail is referenced once, and canonicalization readily produces graphs where several lists share a tail, so when the compact form does not round-trip the graph is re-rendered with explicit `rdf:first`/`rdf:rest` @@ -125,9 +128,14 @@ print(turtle) def canonicalize_rdf_graph(graph: rdflib.Graph, output_format: str = "turtle") -> str ``` -Serializes one graph to a canonical form in the requested format. Use this when +Serializes one graph deterministically in the requested format. Use this when the target is not Turtle, or when RDFC-1.0's own labels are what you want. +Using RDFC-1.0 labels does not promise [canonical N-Quads][rdfc-canonical-quads] +bytes: the requested syntax, ordering, framing and optional prefix/base +presentation belong to this library's contract. This single-graph API does +not expose a standalone RDFC processor or a selectable hash algorithm. + This is the lower-level entry point: blank nodes keep their RDFC-1.0 `c14nN` labels, which are deterministic but sequential, so inserting a triple can renumber the rest. For output kept in version control, prefer @@ -208,6 +216,10 @@ graph and no graph name appears in the output. To keep graph names, relabel quads with `wl_relabel_quads` and serialize the dataset with your own serializer. +**N3 is the Turtle-compatible RDF graph subset.** The `n3` name does not +extend the input model to formulas, implications, variables or arbitrary +Notation3 logic. + **`graph.base` is used on this path**, unlike in `deterministic_turtle`: a base IRI is handed to pyoxigraph, which emits a `@base` directive and RFC 3986-correct relative references. For Turtle, TriG, and N3, valid prefix @@ -325,8 +337,10 @@ a JSON canonicalization scheme, and not a JSON-LD processor. `@graph` and `@set` are **not** protected, and their arrays sort like any other. JSON-LD arrays carry no order unless a container says they do, and -`@set` exists to express "an unordered set of data" (JSON-LD 1.1 §1.7, §4.3.2); -`@list` is the ordered one (§4.3.1). An ordered construct nested inside a +`@set` is unordered and `@list` is ordered under the normative +[JSON-LD 1.1 §9.7 Lists and Sets][jsonld-lists]. The separate +[§4.3 Value Ordering discussion][jsonld-ordering] is informative. +An ordered construct nested inside a `@graph` or `@set` array still keeps its order, because that protection comes from the keyword rather than from the enclosing key. @@ -341,8 +355,11 @@ literal payloads, and terms declared with `@container: @list` or `@type: @json` in a local `@context` are recognized, including keyword aliases, ordered context arrays, inheritance by nested objects, and a `null` reset. Key order inside a `@context` object carries no meaning, so a definition may -name an alias declared after it: Create Term Definition (JSON-LD 1.1 API -§4.2.2) keeps a `defined` map and resolves a referenced term recursively. +name an alias declared after it: [JSON-LD 1.1 API §4.2 Create Term +Definition][jsonld-term-definition] keeps a `defined` map and resolves a +referenced term recursively. Ordered context processing is specified in +[§4.1 Context Processing Algorithm][jsonld-context-processing]. Recognizing +these local ordering rules does not implement the complete API algorithms. Remote contexts, `@import`, scoped contexts and definitions whose ordering cannot be settled locally are never fetched and mark the value unknown; from there every descendant array is left alone, which also covers a `@context: null` @@ -611,5 +628,12 @@ normalized, `rdflib.compare.isomorphic` — which is stricter than rdflib's own non-isomorphic across a tag-case change. It cannot be used to check losslessness in that case. -[rdfc]: https://www.w3.org/TR/rdf-canon/ -[concepts]: https://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal +[rdfc]: https://www.w3.org/TR/2024/REC-rdf-canon-20240521/ +[rdfc-conformance]: https://www.w3.org/TR/2024/REC-rdf-canon-20240521/#conformance +[rdfc-canonical-quads]: https://www.w3.org/TR/2024/REC-rdf-canon-20240521/#canonical-quads +[concepts]: https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-Graph-Literal +[graph-comparison]: https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-graph-equality +[jsonld-lists]: https://www.w3.org/TR/2020/REC-json-ld11-20200716/#lists-and-sets +[jsonld-ordering]: https://www.w3.org/TR/2020/REC-json-ld11-20200716/#sets-and-lists +[jsonld-term-definition]: https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/#create-term-definition +[jsonld-context-processing]: https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/#context-processing-algorithm diff --git a/docs/standards/README.md b/docs/standards/README.md new file mode 100644 index 0000000..3d05f9c --- /dev/null +++ b/docs/standards/README.md @@ -0,0 +1,137 @@ +# Standards profile and original references + +This collection pins the specifications that define the RDF terms and document +syntaxes used by the library. The files in `references/` are complete, +unmodified original HTML or RFC text bodies, including publication status, +authorship and copyright notices. This README is a project-authored scope +summary, not a replacement for those originals. + +The reference directory disables Git text conversion so publisher line endings +remain byte-exact on every checkout platform, including Windows. + +The snapshots provide offline text and HTML fragment lookup. Linked style +sheets, scripts, images, examples and other resources are not mirrored; a local +HTML view need not render exactly like the publisher's site. Open the source +link for the publisher's presentation. A dated edition can contain publisher +errata or editorial updates; the digest identifies the exact bytes retained. + +## Implementation profile + +| Feature | Standard-derived behavior | Scope and project-specific behavior | +| --- | --- | --- | +| Graph serializers | RDF 1.1 Concepts §3.1 triple positions, §3.3 literal terms and §3.6 graph comparison | One `rdflib.Graph`; dataset inputs are rejected. Prefix bindings and graph base are presentation inputs, not RDF graph identity. | +| Turtle, N-Triples, TriG, N-Quads, RDF/XML | Each named RDF 1.1 syntax's grammar and term interpretation | TriG and N-Quads carry only the default graph. Prefix/base presentation can be omitted when it does not preserve terms. Not every generalized graph can be expressed in every syntax. | +| N3 | The Turtle-compatible RDF graph subset | No formulas, implications, variables or arbitrary Notation3 logic. | +| Canonical blank-node labels | The dependency's RDFC-1.0 algorithm | The wrapper has one-graph inputs and no hash-algorithm parameter. It does not claim the standalone processor conformance defined by RDFC §2. | +| Rendered bytes | RDF term fidelity plus each selected syntax | `canonicalize_rdf_graph` uses RDFC labels but does not advertise standardized canonical N-Quads bytes. Sorting, framing and optional compact syntax are project policies. Internal sorted term comparison keys are not standardized canonical byte output. | +| WL labels and diff stability | Canonicalized terms supply deterministic input | WL hashes, collision suffixes and locality are project features, not RDFC canonical labels or a cryptographic commitment scheme. Low-level quad helpers retain named graphs. Directional literals accepted by the dependency are a supported extension, not blanket RDF 1.2 conformance. Embedded triple terms are rejected. | +| JSON-LD graph output | JSON-LD 1.1 expanded RDF representation | A graph serializer, not a general JSON-LD processor. The degraded path supports its documented interoperable subset and rejects unsupported terms. | +| JSON ordering | RFC 8259 data model; JSON-LD §9.7 ordered lists and unordered sets; selected local context-ordering rules | `deterministic_json` is neither JCS nor a JSON-LD processor. It does not fetch remote contexts or implement the complete JSON-LD API algorithms. Python key coercion and non-finite float handling follow the documented Python encoder behavior; strict JSON requires JSON-compatible finite values. | +| IRIs and XML terms | RFC 3986 relative resolution, RFC 3987 IRIs, XML 1.0 characters and XML Namespaces qualified names | Relative/generalized terms use the documented degraded serialization paths where available; this is not an extension of RDF 1.1's absolute-IRI graph model. XML-inexpressible characters are rejected. | + +The exact supported inputs, fallback boundaries, exceptions and reproducibility +conditions are in the [API contract](../api.md). This profile does not enlarge +those guarantees. + +[RDFC §2](references/rdf-canon.html#conformance) defines processor conformance. +[§3.1](references/rdf-canon.html#canon-terms) and +[Appendix A](references/rdf-canon.html#canonical-quads) define canonical N-Quads. +Testing labels or graph isomorphism does not alone test that byte format. +The specification itself also explains that passing its test suite establishes +only the aspects tested, not complete conformance. + +[RDF 1.1 Concepts §3.6](references/rdf11-concepts.html#section-graph-equality) +is the graph-comparison clause; the separate +[§3.3](references/rdf11-concepts.html#section-Graph-Literal) defines literal terms. +For JSON-LD ordering, the normative clause is +[§9.7 Lists and Sets](references/json-ld11.html#lists-and-sets), while +[§4.3 Value Ordering](references/json-ld11.html#sets-and-lists) is informative. +Ordered contexts and recursive term definitions are described by the normative +JSON-LD API [§4.1](references/json-ld11-api.html#context-processing-algorithm) +and [§4.2](references/json-ld11-api.html#create-term-definition) algorithms; +the ordering helper implements only the local facts documented in its API. + +## Reference inventory + +All entries were retrieved on 2026-09-10. Publication dates and status below +refer to the pinned edition, not a claim that no newer edition exists. RFCs +whose originals specify only a month retain month-level publication precision. +The [manifest](manifest.json) records exact requested and resolved URLs, media +types, SHA-256 digests, license references and selected clause anchors. + +| ID | Original copy | Edition | Publisher source | +| --- | --- | --- | --- | +| `RDF11-CONCEPTS` | [RDF 1.1 Concepts and Abstract Syntax](references/rdf11-concepts.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/) | +| `RDFC10` | [RDF Dataset Canonicalization](references/rdf-canon.html) | W3C Recommendation, 21 May 2024 | [Original](https://www.w3.org/TR/2024/REC-rdf-canon-20240521/) | +| `TURTLE11` | [RDF 1.1 Turtle](references/turtle.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-turtle-20140225/) | +| `TRIG11` | [RDF 1.1 TriG](references/trig.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-trig-20140225/) | +| `NTRIPLES11` | [RDF 1.1 N-Triples](references/n-triples.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-n-triples-20140225/) | +| `NQUADS11` | [RDF 1.1 N-Quads](references/n-quads.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-n-quads-20140225/) | +| `RDFXML11` | [RDF 1.1 XML Syntax](references/rdf-syntax-grammar.html) | W3C Recommendation, 25 February 2014 | [Original](https://www.w3.org/TR/2014/REC-rdf-syntax-grammar-20140225/) | +| `JSONLD11` | [JSON-LD 1.1](references/json-ld11.html) | W3C Recommendation, 16 July 2020 | [Original](https://www.w3.org/TR/2020/REC-json-ld11-20200716/) | +| `JSONLD11-API` | [JSON-LD 1.1 Processing Algorithms and API](references/json-ld11-api.html) | W3C Recommendation, 16 July 2020 | [Original](https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/) | +| `XML10` | [Extensible Markup Language (XML) 1.0 (Fifth Edition)](references/xml.html) | W3C Recommendation, 26 November 2008 | [Original](https://www.w3.org/TR/2008/REC-xml-20081126/) | +| `XMLNS10` | [Namespaces in XML 1.0 (Third Edition)](references/xml-names.html) | W3C Recommendation, 8 December 2009 | [Original](https://www.w3.org/TR/2009/REC-xml-names-20091208/) | +| `RFC3986` | [Uniform Resource Identifier (URI): Generic Syntax](references/rfc3986.txt) | Standards Track, January 2005 | [Original](https://www.rfc-editor.org/rfc/rfc3986.txt) | +| `RFC3987` | [Internationalized Resource Identifiers (IRIs)](references/rfc3987.txt) | Standards Track, January 2005 | [Original](https://www.rfc-editor.org/rfc/rfc3987.txt) | +| `RFC8259` | [The JavaScript Object Notation (JSON) Data Interchange Format](references/rfc8259.txt) | Standards Track, December 2017 | [Original](https://www.rfc-editor.org/rfc/rfc8259.txt) | + +## Notices and redistribution + +Original publisher notices remain in every specification. The project's Apache-2.0 +license does not replace third-party document terms. These copies preserve +source links, publication status, authorship, copyright and disclaimers; the +project does not modify the standards bodies. + +The [2002 W3C document-use license](references/w3c-document-license-2002.html) +records the document-use terms active for the 2008, 2009 and 2014 editions. +Their original unversioned document-use link resolves on retrieval to the +[2023 document license](references/w3c-document-license.html); both are retained +and their roles distinguished in the manifest. The JSON-LD Recommendations +explicitly link the +[2015 Software and Document license](references/w3c-software-document-2015.html). +RDFC explicitly links the +[2023 Software and Document license](references/w3c-software-document-2023.html). +These document licenses are not interchangeable with test-suite licenses. + +RFC 3986 and RFC 3987 retain their complete embedded copyright and BCP 78 +notices. [RFC 3667](references/rfc3667.txt) is the February 2004 BCP 78 text +applicable to their January 2005 publication. RFC 8259 retains its complete +IETF Trust notice and its original license-info link, whose resolved +[index](references/ietf-license-info.html) is pinned for provenance. +[Trust Legal Provisions 5.0](references/ietf-tlp-5.html), effective 25 March +2015, is retained as the publisher's text including its stated clerical +correction to the BSD license name. Its §3.c permits redistribution of +unmodified IETF documents outside the IETF Standards Process. + +## Verification and maintenance + +Run `python scripts/check_standards.py` from the project root. The command is +dependency-free and offline: it validates the schema, complete expected +reference inventory, unique identities and paths, contained paths, original +text identities, digests, license relationships and selected HTML anchors. +It never downloads documents or rewrites hashes. The generic tests in +`tests/standards/` cover valid catalogs and malformed or corrupted evidence. +Catalog validation is not a claim that every copied clause is implemented. + +To update a reference: + +1. Select the exact dated Recommendation or numbered RFC and inspect its + publication status and redistribution notice. Do not replace a pinned + edition with an unreviewed moving latest URL. +2. Download the original complete body without reformatting, rewriting links + or changing line endings. Reject error pages, challenge pages and incomplete + responses. Record requested and resolved URLs and the actual retrieval date. +3. Verify the original title, publication identity and copyright/status notice; + retain any newly applicable license text and distinguish redirected current + notices from publication-era terms. +4. Update the manifest digest, provenance and clause anchors together. Cite the + pinned edition, label informative explanations, and review the implementation + profile and affected requirement/test mappings for changes in scope. +5. Run the offline checker and standards tests, then the full source and + installed-wheel suites. Confirm the source distribution includes the + collection and licenses. Runtime wheels intentionally exclude these assets. + +The catalog schema version changes when its structure changes. The checker +keeps an explicit expected specification inventory; adding or removing a +standard requires a reviewed change to that inventory as well as the catalog. diff --git a/docs/standards/manifest.json b/docs/standards/manifest.json new file mode 100644 index 0000000..6f42949 --- /dev/null +++ b/docs/standards/manifest.json @@ -0,0 +1,426 @@ +{ + "schema_version": 1, + "references": [ + { + "id": "RDF11-CONCEPTS", + "title": "RDF 1.1 Concepts and Abstract Syntax", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/", + "path": "references/rdf11-concepts.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "3838c992097f72ee8784b6c96194d9879f86f2e08f53ced5a05aa4031750c5ac", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "section-graph-equality", + "section": "3.6 Graph Comparison", + "normative": true + }, + { + "id": "section-Graph-Literal", + "section": "3.3 Literals", + "normative": true + }, + { + "id": "section-triples", + "section": "3.1 Triples", + "normative": true + } + ] + }, + { + "id": "RDFC10", + "title": "RDF Dataset Canonicalization", + "edition": "21 May 2024", + "publication_date": "2024-05-21", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2024/REC-rdf-canon-20240521/", + "resolved_url": "https://www.w3.org/TR/2024/REC-rdf-canon-20240521/", + "path": "references/rdf-canon.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "330eb4f00c5f12300e23cb7a7b979bdfc910890a41bfb87a93327d7b43161fd0", + "license_ids": [ + "W3C-SOFTWARE-DOCUMENT-2023" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "conformance", + "section": "2 Conformance", + "normative": true + }, + { + "id": "canon-terms", + "section": "3.1 Terms defined by this specification", + "normative": true + }, + { + "id": "canonical-quads", + "section": "A A Canonical form of N-Quads", + "normative": true + } + ] + }, + { + "id": "TURTLE11", + "title": "RDF 1.1 Turtle", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-turtle-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-turtle-20140225/", + "path": "references/turtle.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "f1ff33edbd9dbac6a472e001064ef70b4aee849972f3d8b5afa837b5f9cc6580", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [] + }, + { + "id": "TRIG11", + "title": "RDF 1.1 TriG", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-trig-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-trig-20140225/", + "path": "references/trig.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "90125fee148e9ade1682649cd2f4fe82c45640445dd1ffca3fb8651b4fe1f7e1", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [] + }, + { + "id": "NTRIPLES11", + "title": "RDF 1.1 N-Triples", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-n-triples-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-n-triples-20140225/", + "path": "references/n-triples.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "c1b0128244a787b408f5ec6f9a45ac148b998191f5a4341c1979a397722ac036", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [] + }, + { + "id": "NQUADS11", + "title": "RDF 1.1 N-Quads", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-n-quads-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-n-quads-20140225/", + "path": "references/n-quads.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "0e0f395f9956e97cc4477a54c07c69747a4a8ecfc29d6d9ccabb9b662c8efc91", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [] + }, + { + "id": "RDFXML11", + "title": "RDF 1.1 XML Syntax", + "edition": "25 February 2014", + "publication_date": "2014-02-25", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2014/REC-rdf-syntax-grammar-20140225/", + "resolved_url": "https://www.w3.org/TR/2014/REC-rdf-syntax-grammar-20140225/", + "path": "references/rdf-syntax-grammar.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "69693f6e9cc399589f8e6f3f08d60e908a38effdb9a2745c70b0f0752fd2f7e5", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [] + }, + { + "id": "JSONLD11", + "title": "JSON-LD 1.1", + "edition": "16 July 2020", + "publication_date": "2020-07-16", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2020/REC-json-ld11-20200716/", + "resolved_url": "https://www.w3.org/TR/2020/REC-json-ld11-20200716/", + "path": "references/json-ld11.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "9e2c9972d0f60bc744e975731643a9a63d410afc6b682eb8898ad2720e452866", + "license_ids": [ + "W3C-SOFTWARE-DOCUMENT-2015" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "lists-and-sets", + "section": "9.7 Lists and Sets", + "normative": true + }, + { + "id": "sets-and-lists", + "section": "4.3 Value Ordering", + "normative": false + }, + { + "id": "conformance", + "section": "2 Conformance", + "normative": true + } + ] + }, + { + "id": "JSONLD11-API", + "title": "JSON-LD 1.1 Processing Algorithms and API", + "edition": "16 July 2020", + "publication_date": "2020-07-16", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/", + "resolved_url": "https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/", + "path": "references/json-ld11-api.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "380ddb64232c701a8ff969e22646451e20fe66d264e34a5bc4c5b018e8c77f55", + "license_ids": [ + "W3C-SOFTWARE-DOCUMENT-2015" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "context-processing-algorithm", + "section": "4.1 Context Processing Algorithm", + "normative": true + }, + { + "id": "create-term-definition", + "section": "4.2 Create Term Definition", + "normative": true + }, + { + "id": "conformance", + "section": "3 Conformance", + "normative": true + } + ] + }, + { + "id": "XML10", + "title": "Extensible Markup Language (XML) 1.0 (Fifth Edition)", + "edition": "26 November 2008", + "publication_date": "2008-11-26", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2008/REC-xml-20081126/", + "resolved_url": "https://www.w3.org/TR/2008/REC-xml-20081126/", + "path": "references/xml.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "f58a4b9e1e5b8bac13fb55c4e5c7c8c5e2c176aa45ee68e2f1ab2498511927ec", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "charsets", + "section": "2.2 Characters", + "normative": true + }, + { + "id": "sec-line-ends", + "section": "2.11 End-of-Line Handling", + "normative": true + } + ] + }, + { + "id": "XMLNS10", + "title": "Namespaces in XML 1.0 (Third Edition)", + "edition": "8 December 2009", + "publication_date": "2009-12-08", + "status": "W3C Recommendation", + "source_url": "https://www.w3.org/TR/2009/REC-xml-names-20091208/", + "resolved_url": "https://www.w3.org/TR/2009/REC-xml-names-20091208/", + "path": "references/xml-names.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "b4a649e5fdab9852d68eca21442481599164949bcdee5549f2ec7e38fb3cd3a8", + "license_ids": [ + "W3C-DOCUMENT-2002", + "W3C-DOCUMENT-RESOLVED" + ], + "notice": "Original copyright, publication status and linked document-use or permissive document license notice are retained in the unmodified HTML.", + "anchors": [ + { + "id": "ns-qualnames", + "section": "4 Qualified Names", + "normative": true + } + ] + }, + { + "id": "RFC3986", + "title": "Uniform Resource Identifier (URI): Generic Syntax", + "edition": "January 2005", + "publication_date": "2005-01", + "status": "Standards Track", + "source_url": "https://www.rfc-editor.org/rfc/rfc3986.txt", + "resolved_url": "https://www.rfc-editor.org/rfc/rfc3986.txt", + "path": "references/rfc3986.txt", + "media_type": "text/plain", + "retrieved_at": "2026-09-10", + "sha256": "3102dae4b68cebe40337730312fcb612297b8928547267e8b3d1ee6002b2d683", + "license_ids": [ + "BCP78-2004" + ], + "notice": "Complete Copyright Notice and Full Copyright Statement where present are retained in the unmodified RFC.", + "anchors": [] + }, + { + "id": "RFC3987", + "title": "Internationalized Resource Identifiers (IRIs)", + "edition": "January 2005", + "publication_date": "2005-01", + "status": "Standards Track", + "source_url": "https://www.rfc-editor.org/rfc/rfc3987.txt", + "resolved_url": "https://www.rfc-editor.org/rfc/rfc3987.txt", + "path": "references/rfc3987.txt", + "media_type": "text/plain", + "retrieved_at": "2026-09-10", + "sha256": "7cc9e3c4e61ea326130d29d959b723209fe3a6c75cdcfb5badbd315d96cd7878", + "license_ids": [ + "BCP78-2004" + ], + "notice": "Complete Copyright Notice and Full Copyright Statement where present are retained in the unmodified RFC.", + "anchors": [] + }, + { + "id": "RFC8259", + "title": "The JavaScript Object Notation (JSON) Data Interchange Format", + "edition": "December 2017", + "publication_date": "2017-12", + "status": "Standards Track", + "source_url": "https://www.rfc-editor.org/rfc/rfc8259.txt", + "resolved_url": "https://www.rfc-editor.org/rfc/rfc8259.txt", + "path": "references/rfc8259.txt", + "media_type": "text/plain", + "retrieved_at": "2026-09-10", + "sha256": "61a5378f4255c720beb2a4b4a63b29540147c140f36988bf086291989b4cd2d7", + "license_ids": [ + "IETF-LICENSE-INDEX", + "IETF-TLP5" + ], + "notice": "Complete Copyright Notice and Full Copyright Statement where present are retained in the unmodified RFC.", + "anchors": [] + } + ], + "licenses": [ + { + "id": "W3C-DOCUMENT-2002", + "title": "Document license - 2002 version", + "source_url": "https://www.w3.org/copyright/document-license-2002/", + "resolved_url": "https://www.w3.org/copyright/document-license-2002/", + "path": "references/w3c-document-license-2002.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "62e6df0a226bfed9de8996e4e896113cdfb33cb33f80038e56f761abdc70d8f5", + "notice": "Document-use terms active from 31 December 2002; originals retain copyright, status and source links." + }, + { + "id": "W3C-DOCUMENT-RESOLVED", + "title": "Document license - 2023 version", + "source_url": "https://www.w3.org/Consortium/Legal/copyright-documents", + "resolved_url": "https://www.w3.org/copyright/document-license-2023/", + "path": "references/w3c-document-license.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "4bc849ad8fc856e93478400332f409d209bdb7ab3ec0f346e88e9c23b6d2b9ae", + "notice": "Resolved destination of the original document-use link on the retrieval date; not presented as the publication-era text." + }, + { + "id": "W3C-SOFTWARE-DOCUMENT-2015", + "title": "Software and Document license - 2015 version", + "source_url": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document", + "resolved_url": "https://www.w3.org/copyright/software-license-2015/", + "path": "references/w3c-software-document-2015.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "254f76f6eb153b1a874645015489f24844fe117585a422f9f53ea3f359806919", + "notice": "Permissive license explicitly linked by both JSON-LD 2020 Recommendations." + }, + { + "id": "W3C-SOFTWARE-DOCUMENT-2023", + "title": "Software and Document license - 2023 version", + "source_url": "https://www.w3.org/copyright/software-license-2023/", + "resolved_url": "https://www.w3.org/copyright/software-license-2023/", + "path": "references/w3c-software-document-2023.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "ec32c12624d9dc038328872f288355f9e3ff59f2c1ab575c631868eb894415c1", + "notice": "Permissive license explicitly linked by the RDFC 2024 Recommendation." + }, + { + "id": "BCP78-2004", + "title": "IETF Rights in Contributions", + "source_url": "https://www.rfc-editor.org/rfc/rfc3667.txt", + "resolved_url": "https://www.rfc-editor.org/rfc/rfc3667.txt", + "path": "references/rfc3667.txt", + "media_type": "text/plain", + "retrieved_at": "2026-09-10", + "sha256": "f01b0192e5865b77f18f52a2d1afa11cf22b8c06c0d1769d37ecd72e7aa52adc", + "notice": "RFC 3667, BCP 78, February 2004; rights and permissions in section 3.3 and required notices in section 5. RFC 3986 and RFC 3987 retain their complete embedded notices." + }, + { + "id": "IETF-LICENSE-INDEX", + "title": "Trust Legal Provisions", + "source_url": "https://trustee.ietf.org/license-info", + "resolved_url": "https://trustee.ietf.org/documents/trust-legal-provisions/", + "path": "references/ietf-license-info.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "e0350a0a6272f4cb8de5359cefec783fc3eba55ea2d2b7c3ffb603231508803f", + "notice": "Resolved destination of the license-info link printed in RFC 8259; index provenance only, not the license text." + }, + { + "id": "IETF-TLP5", + "title": "Trust Legal Provisions", + "source_url": "https://trustee.ietf.org/documents/trust-legal-provisions/tlp-5/", + "resolved_url": "https://trustee.ietf.org/documents/trust-legal-provisions/tlp-5/", + "path": "references/ietf-tlp-5.html", + "media_type": "text/html", + "retrieved_at": "2026-09-10", + "sha256": "c63e5191b6909115beb3ebbed489c24f600d0b7afc8420f43b8fa337eb489a78", + "notice": "TLP 5.0, effective 25 March 2015; this original publisher page includes the 21 September 2021 clerical correction of the BSD license name. Section 3.c permits copying unmodified documents outside the IETF Standards Process; all RFC 8259 notices are retained." + } + ] +} diff --git a/docs/standards/references/.gitattributes b/docs/standards/references/.gitattributes new file mode 100644 index 0000000..fa1385d --- /dev/null +++ b/docs/standards/references/.gitattributes @@ -0,0 +1 @@ +* -text diff --git a/docs/standards/references/ietf-license-info.html b/docs/standards/references/ietf-license-info.html new file mode 100644 index 0000000..1ef64e3 --- /dev/null +++ b/docs/standards/references/ietf-license-info.html @@ -0,0 +1,352 @@ + + + + + + + +Trust Legal Provisions (TLP) – IETF Trust + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+ +
+
+ +
+
+

Trust Legal Provisions (TLP)

+ + +
+

The IETF Trust was formed on December 15, 2005, for, among other things, the purpose of acquiring, holding, maintaining and licensing certain existing and future intellectual property used in connection with the Internet standards process and its administration, for the advancement of science and technology associated with the Internet and related technology.

+

Accordingly, pursuant to RFC 5378, Contributors to the IETF Standards Process grant the IETF Trust certain licenses with respect to their IETF Contributions. In RFC 5377, the IETF Community has provided the IETF Trust with guidance regarding licenses that the IETF Trust should grant to others with respect to such IETF Contributions and IETF Documents.

+

These Legal Provisions describe the rights and licenses that the IETF Trust grants to others with respect to such IETF Contributions and IETF Documents; as well as certain restrictions, limitations and notices relating to IETF Documents.

+

The standardized license text referred to in RFC 5378 is included in the Trust Legal Provisions, linked below.

+

The Trustees request that discussion of this topic be on the tlp-interest list, tlp-interest@ietf.org, with cc to trustees@ietf.org. This list can be joined here: https://www.ietf.org/mailman/listinfo/tlp-interest

+

Trust Legal Provisions (TLP)

+

Current TLP

+

Corrected Trust Legal Provisions 5.0 (PDF)

+

Frequently Asked Questions

+

See the relevant sections of the Trust FAQ. RFC5378 Instructions are documented in the IETF Trust FAQ.

+

TLP Archive

+
+ + + + + + + + +
+ + + + +
+ +

Code Components

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Code ComponentsFileDate PublishedDate EffectiveDate Obsoleted
3.0Code Components 3.0Apr 23, 2009Apr 23, 2009
2.0Code Components 2.0Nov 24, 2008Nov 24, 2008Apr 23, 2009
1.0Code Components 1.0Nov 10, 2008Nov 10, 2008Nov 24, 2008
+

 

+
+ + +
+ +
+ + +
+ + + + +
+ + +
+
+ + + + + + + + + + + + diff --git a/docs/standards/references/ietf-tlp-5.html b/docs/standards/references/ietf-tlp-5.html new file mode 100644 index 0000000..add6d91 --- /dev/null +++ b/docs/standards/references/ietf-tlp-5.html @@ -0,0 +1,376 @@ + + + + + + + +Corrected Legal Provisions Relating to IETF Documents – IETF Trust + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+ +
+
+ +
+
+

Corrected Legal Provisions Relating to IETF Documents

+ + +
+

Note: in prior versions of these provisions, the software license was erroneously called the “Simplified BSD License” rather than the “Revised BSD License”, and many documents that refer to these provisions copied the erroneous name. The IETF Trust corrected the error on September 21, 2021. The license text itself was always that of the Revised BSD License and has not changed.

+

Effective Date: March 25, 2015

+

1. Background

+

The IETF Trust was formed on December 15, 2005, for, among other things, the purpose of acquiring, holding, maintaining and licensing certain existing and future intellectual property used in connection with the Internet standards process and its administration, for the advancement of science and technology associated with the Internet and related technology. Accordingly, pursuant to RFC 5378, Contributors grant the IETF Trust certain licenses with respect to their IETF Contributions. In RFC 5377, the IETF Community has provided the IETF Trust with guidance regarding licenses that the IETF Trust should grant to others with respect to such IETF Contributions and IETF Documents. These Legal Provisions describe the rights and licenses that the IETF Trust grants to others with respect to such IETF Contributions and IETF Documents; as well as certain restrictions, limitations and notices relating to IETF Documents. These Legal Provisions also apply to other document streams that have requested that the IETF Trust act as licensing administrator, as described in Section 8 below. Capitalized terms used in these Legal Provisions that are not otherwise defined have the meanings set forth in RFC 5378.

+

2. Applicability of these Legal Provisions.

+

  a. These Legal Provisions are effective as of March 25, 2015 (the “Effective Date”).

+

b. The licenses granted by the IETF Trust pursuant to these Legal Provisions apply only with respect to (i) IETF Contributions (including Internet-Drafts) that are submitted to the IETF following the Effective Date, and (ii) IETF RFCs and other IETF Documents that are published after the Effective Date.

+

c. IETF Contributions made, and IETF Documents published, prior to the Effective Date (“Pre-Existing IETF Documents”) remain subject to the licensing provisions of the IETF copyright policy document in effect at the time of their contribution or publication, as applicable, including RFCs 1310, 1602, 2026, 3978 and 4748 and previous versions of these Legal Provisions.

+

d. In most cases, rights to Pre-Existing IETF Documents that are not expressly granted under these RFCs can only be obtained by requesting such rights directly from the document authors. The IETF Trust and the Internet Society do not become involved in making such requests to document authors.

+

e. These Legal Provisions may be amended from time to time by the IETF Trust in a manner consistent with the guidance provided by the IETF community and its own operating procedures. Any amendment to these Legal Provisions shall be posted for review at https://trustee.ietf.org/documents/policies-and-procedures/ and shall become effective on a date specified by the IETF Trust, but no earlier than thirty (30) days following its posting. Such amendment shall apply with respect to all IETF Contributions made and IETF Documents published following the effective date of such amendment. All prior versions of these Legal Provisions shall continue to be posted at https://trustee.ietf.org/documents/policies-and-procedures/ for reference with respect to IETF Contributions and IETF Documents as to which they may apply.

+

3. Licenses to IETF Documents and IETF Contributions.

+

  a. License For Use Within the IETF Standards Process. The IETF Trust hereby grants to each participant in the IETF Standards Process, to the greatest extent that it is permitted to do so, a non-exclusive, royalty-free, worldwide right and license under all copyrights and rights of authors granted to the IETF Trust:

+

     i. to copy, publish, display and distribute IETF Contributions and IETF Documents, in whole or in part, as part of the IETF Standards Process, and

+

ii. to translate IETF Contributions and IETF Documents, in whole or part, into languages other than English as part of the IETF Standards Process, and

+

iii. unless explicitly disallowed in the notices contained in an IETF Contribution or IETF Document (as specified in Section 6.c below), to modify or prepare derivative works of such IETF Contributions or IETF Documents, in whole or in part, as part of the IETF Standards Process.

+

  b. IETF Standards Process. The term IETF Standards Process has the meaning assigned to it in RFC 5378. In addition, the IETF Trust interprets the IETF Standards Process to include the archiving of IETF Documents in perpetuity for reference in support of IETF activities and the implementation of IETF standards and specifications.

+

  c. Licenses For Use Outside the IETF Standards Process. In addition to the rights granted with respect to Code Components described in Section 4 below, the IETF Trust hereby grants to each person who wishes to exercise such rights, to the greatest extent that it is permitted to do so, a non-exclusive, royalty-free, worldwide right and license under all copyrights and rights of authors:

+

       i. to copy, publish, display and distribute IETF Contributions and IETF Documents in full and without modification,

+

ii. to translate IETF Contributions and IETF Documents into languages other than English, and to copy, publish, display and distribute such translated IETF Contributions and IETF Documents in full and without modification,

+

iii. to copy, publish, display and distribute unmodified portions of IETF Contributions and IETF Documents and translations thereof, provided that:

+

(x) each such portion is clearly attributed to IETF and identifies the RFC or other IETF Document or IETF Contribution from which it is taken,

+

(y) all IETF legends, legal notices and indications of authorship contained in the original IETF RFC must also be included where any substantial portion of the text of an IETF RFC, and in any event where more than one-fifth of such text, is reproduced in a single document or series of related documents.

+

  d. Licenses that are not Granted. The following licenses are not granted pursuant to these Legal Provisions:

+

i. any license to modify IETF Contributions or IETF Documents, or portions thereof (other than to make translations or to extract, use and modify Code Components as permitted under the licenses granted under Section 4 of these Legal Provisions) in any context outside the IETF Standards Process, or

+

ii. any license to publish, display or distribute IETF Contributions or IETF Documents, or portions thereof, without the required legends and notices described in these Legal Provisions.

+

  e. Requesting Additional Rights. Anyone who wishes to request license rights from the IETF Trust in addition to those granted under these Legal Provisions may submit such request to trustees@ietf.org. Such request will be considered by the IETF Trust, which will make a decision regarding the request in its sole discretion and inform the requester of its disposition. In addition, individual Contributors may be contacted regarding licenses to their IETF Contributions. The IETF Trust does not limit the ability of IETF Contributors to license their Contributions, so long as those licenses do not affect the rights granted to the IETF Trust under RFC 5378.

+

4. License to Code Components.

+

  a. Definition. IETF Contributions and IETF Documents often include components intended to be directly processed by a computer (“Code Components”). A list of common Code Components can be found at https://trustee.ietf.org/documents/trust-legal-provisions/code-components-list-3/

+

  b. Identification. Text in IETF Contributions and IETF Documents of the types identified in Section 4.a above shall constitute “Code Components”. In addition, any text found between the markers <CODE BEGINS> and <CODE ENDS>, or otherwise clearly labeled as a Code Component, shall be considered a “Code Component”.

+

  c. License. In addition to the licenses granted under Section 3, unless one of the legends contained in Section 6.c.i or 6.c.ii is included in an IETF Document containing Code Components, such Code Components are also licensed to each person who wishes to receive such a license on the terms of the “Revised BSD License”, as described below. If a licensee elects to apply the BSD License to a Code Component, then the additional licenses and restrictions set forth in Section 3 and elsewhere in these Legal Provisions shall not apply thereto. Note that this license is specifically offered for IETF Documents and may not be available for Alternate Stream documents. See Section 8 for licensing information for the appropriate stream.

+

BSD License:

+

Copyright (c) <insert year> IETF Trust and the persons identified as authors of the code. All rights reserved.Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

+
    +
  • +
      +
    • +
        +
      • +
          +
        • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
          • +
        • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
          • +
        • Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission.
          • +
        +
        • +
      +
      • +
    +
    • +
+

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+

The above BSD License is intended to be compatible with the Revised BSD License template published at https://opensource.org/licenses/BSD-3-Clause.

+

  d. Attribution. Those who use Code Components under the license granted under Section 4.c above are requested to attribute each such Code Component to IETF and identify the RFC or other IETF Document or IETF Contribution from which it is taken. Such attribution may be placed in the code itself (e.g., “This code was derived from IETF RFC [insert RFC number]. Please reproduce this note if possible.”), or any other reasonable location.

+

  e. BSD License Text. For purposes of compliance with the redistribution clauses of the Revised BSD License set forth in Section 4.c above, it is permissible, when using Code Components extracted from IETF Contributions and IETF Documents, either (1) to reproduce the entire text of the Revised BSD License set forth in Section 4.c above as part of such Code Component, or (2) to include in such Code Component the legend set forth in Section 6.d below.

+

5. License Limitations.

+

   a. No Patent License. The licenses granted under these Legal Provisions shall not be deemed to grant any right under any patent, patent application or similar intellectual property right.

+

  b. Supersedure. The terms of any license granted under these Legal Provisions may be superseded by a written agreement between the IETF Trust and the licensee that specifically references and supersedes the relevant provisions of these Legal Provisions, except that (i) the IETF Trust shall in no event be authorized to grant rights with respect to any Contribution in excess of those which it has been granted by the Contributor, and (ii) the rights granted shall not be less than those otherwise granted under these Legal Provisions.

+

  c. Pre-5378 Material. In some cases, IETF Contributions or IETF Documents may contain material from IETF Contributions or IETF Documents published or made publicly available before November 10, 2008 as to which the persons controlling the copyright in such material have not granted rights to the IETF Trust under the terms of RFC 5378 (“Pre-5378 Material”). If a Contributor includes the legend contained in Section 6.c.iii of these Legal Provisions on such IETF Contributions or IETF Documents containing Pre-5378 Materials, the IETF Trust agrees that it shall not grant any third party the right to use such Pre-5378 Material outside the IETF Standards Process unless and until it has obtained sufficient rights to do so from the persons controlling the copyright in such Pre-5378 Material. Where practical, Contributors are encouraged to identify which portions of such IETF Contributions and IETF Documents contain Pre-5378 Material, including the source (by RFC number or otherwise) of the Pre-5378 Material.

+

6. Text To Be Included in IETF Documents. The following text must be included in each IETF Document as specified below. The IESG shall specify the manner and location of such text for Internet-Drafts. The RFC Editor shall specify the manner and location of such text for RFCs. The copyright notice specified in 6.b below shall be placed so as to give reasonable notice of the claim of copyright.

+

  a. Submission Compliance for Internet-Drafts. In each Internet-Draft:

+

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

+

  b. Copyright and License Notice. In each Document (including RFCs and Internet-Drafts):

+

     i. Copyright and License Notice.

+

Copyright (c) <insert year> IETF Trust and the persons identified as the document authors. All rights reserved.

+

This document is subject to BCP 78 and the IETF Trust’s Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.

+

     ii. Alternate Stream Documents Copyright and License Notice. In all Alternate Stream Documents (including RFCs and Internet-Drafts):

+

Copyright (c) <insert year> IETF Trust and the persons identified as the document authors. All rights reserved.

+

This document is subject to BCP 78 and the IETF Trust’s Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this

+

document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

+

  c. Derivative Works and Publication Limitations. If a Contributor chooses to limit the right to make modifications and derivative works of an IETF Contribution, then one of the notices in clause (i) or (ii) below must be included. Note that an IETF Contribution with such a notice cannot become a Standards Track document or, in most cases, a working group document. If an IETF Contribution contains pre-5378 Material as to which the IETF Trust has not been granted, or may not have been granted, the necessary permissions to allow modification of such pre-5378 Material outside the IETF Standards Process, then the notice in clause (iii) may be included by the Contributor of such IETF Contribution to limit the right to make modifications to such pre-5378 Material outside the IETF Standards Process.

+

     i. If the Contributor does not wish to allow modifications, but does wish to allow publication as an RFC:

+

This document may not be modified, and derivative works of it may not be created, except to format it for publication as an RFC or to translate it into languages other than English.

+

     ii. If the Contributor does not wish to allow modifications nor to allow publication as an RFC:

+

This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.

+

     iii. If an IETF Contribution contains pre-5378 Material as to which the IETF Trust has not been granted, or may not have been granted, the necessary permissions to allow modification of such pre-5378 Material outside the IETF Standards Process:

+

This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.

+

  d. BSD License Notification. In lieu of the complete text of the Revised BSD License set forth in Section 4.c, a person who elects to license a Code Component under the Revised BSD License as described in Section 4.c may use the following notification in the program or other file that includes the Code Component:

+

Copyright (c) <insert year> IETF Trust and the persons identified as authors of the code. All rights reserved.

+

Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Revised BSD License set forth in Section 4.c of the IETF Trust’s Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info).

+

7. Terms Applicable to All IETF Documents. The following legal terms apply to all IETF Documents:

+

  a. ALL DOCUMENTS AND THE INFORMATION CONTAINED THEREIN ARE PROVIDED ON AN “AS IS” BASIS AND THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, THE INTERNET ENGINEERING TASK FORCE AND ANY APPLICABLE MANAGERS OF ALTERNATE STREAM DOCUMENTS, AS DEFINED IN SECTION 8 BELOW, DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION THEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

+

b. The IETF Trust takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in any IETF Document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights.

+

c. Copies of Intellectual Property disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at https://www.ietf.org/ipr.

+

d. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement any standard or specification contained in an IETF Document. Please address the information to the IETF at ietf-ipr@ietf.org.

+

e. The definitive version of an IETF Document is that published by, or under the auspices of, the IETF. Versions of IETF Documents that are published by third parties, including those that are translated into other languages, should not be considered to be definitive versions of IETF Documents. The definitive version of these Legal Provisions is that published by, or under the auspices of, the IETF. Versions of these Legal Provisions that are published by third parties, including those that are translated into other languages, should not be considered to be definitive versions of these Legal Provisions.

+

f. For the avoidance of doubt, each Contributor licenses each Contribution that he or she makes to the IETF Trust pursuant to the provisions of RFC 5378. No language to the contrary, or terms, conditions or rights that differ from or are inconsistent with the rights and licenses granted under RFC 5378, shall have any effect and shall be null and void, whether published or posted by such Contributor, or included with or in such Contribution.

+

8. Application to non-IETF Stream Documents

+

  a. General. These Legal Provisions have been developed by the IETF Trust for the benefit and use of the IETF community in accordance with the guidance provided in RFC 5377. As such, these Legal Provisions apply to all IETF Contributions and IETF Documents that are in the “IETF Document Stream” as defined in Section 5.1.1 of RFC 4844 (i.e., those that are contributed, developed, edited and published as part of the IETF Standards Process). As indicated in Section 4 of RFC 5378, the IETF rules regarding copyrights (which are embodied in these Legal Provisions) do not by their terms cover documents or materials contributed or published outside of the IETF Document Stream, even if they are referred to as Internet-Drafts or RFCs and/or published by the RFC Editor. The IAB Document Stream, the IRTF Document Stream and the Independent Submission Stream, each as defined in Section 5.1 of RFC 4844 are referred to collectively herein as “Alternate Streams”.

+

  b. Adoption by Alternate Streams. The legal rules that apply to documents in Alternate Streams are established by the managers of those Alternate Streams as defined in RFC 4844. (i.e., the Internet Architecture Board (IAB), Internet Research Steering Group (IRSG) and Independent Submission Editor). These managers may elect, through their own internal processes, to cause these Legal Provisions to be applied to documents contributed to them for development, editing and publication in their respective Alternate Streams. If an Alternate Stream manager elects to adopt these Legal Provisions and to utilize the IETF Trust as the licensing administrator for such Alternate Stream, the IETF Trust will update these Legal Provisions to reflect the specific manner in which it will so act, and shall do so consistently with the stated wishes of the Alternate Stream manager to the extent consistent with the IETF Trust’s legal obligations and the instructions of the IETF community embodied in RFC 5377 and elsewhere.

+

  c. Alternate Stream License.

+

     i. Unless otherwise specified below, for each Alternate Stream for which the IETF Trust acts as licensing administrator, from the date on which these Legal Provisions are effective with respect to such Alternate Stream (as specified below) the IETF Trust shall accept licenses of copyrights in documents granted to the IETF Trust by contributors to Alternate Stream as though granted pursuant to RFC 5378, and shall grant licenses to others on the terms of these Legal Provisions.

+

ii. Each occurrence of the term “IETF Contribution” and “IETF Document” in these Legal Provisions shall be read to mean a Contribution or document in such Alternate Stream, as the case may be. The disclaimer in Section 7.a of these Legal Provisions shall apply to the manager of such Alternate Stream as defined in RFC 4844 as though such manager were expressly listed in Section 7.a.

+

iii. The license grant in Section 3.a of these Legal Provisions with respect to Alternate Stream documents shall not be limited to the IETF Standards Process, and all references to the IETF Standards Process in Section 3.a shall be omitted with respect to licenses of Alternate Stream documents, and correspondingly Section 3.c hereof shall not apply with respect to Alternate Stream documents.

+

iv. Alternate Stream contributions made, and Alternate Stream documents published, prior to the application of these Legal Provisions to such Alternate Stream remain subject to the licensing provisions in effect for such Alternate Stream at the time of their contribution or publication, as applicable.

+

  d. Responsibility of Alternate Stream Contributors. Sections 5.c and 6.c.iii of these Legal Provisions shall not apply to Alternate Stream documents, thus contributors of Contribution to Alternate Streams must assure themselves that they comply with the representations and warranties required under RFC 5378, including under Section 5.6 of RFC 5378, with respect to the entirety of their Alternate Stream Contributions prior to making the contribution.

+

  e. IAB Document Stream. Pursuant to Section 11 of RFC 5378, the IAB requested, as of April 4, 2008, that the IETF Trust act as licensing administrator for the IAB Document Stream and that these Legal Provisions be applied to documents submitted and published in the IAB Document Stream following the Effective Date of RFC 5378. Section 4 of these Legal Provisions shall not apply to documents in the IAB Document Stream, and all references to Section 4 hereof shall be disregarded with respect to documents in the IAB Document Stream pursuant to RFC 5745 published on December 21, 2009.

+

  f. Independent Submission Stream. Pursuant to RFC 5744 published on December 17, 2009, the manager of the Independent Submission Stream has requested that the IETF Trust act as licensing administrator for the Independent Submission Stream and that these Legal Provisions be applied to documents submitted and published in the Independent Submission Stream following December 28, 2009. Section 4 of these Legal Provisions shall not apply to documents in the Independent Submission Stream, and all references to Section 4 hereof shall be disregarded with respect to documents in the Independent Submission Stream.

+

  g. IRTF Document Stream. Pursuant to RFC 5743 published on December 24, 2009, the manager of the IRTF Document Stream has requested that the IETF Trust act as licensing administrator for the IRTF Document Stream and that these Legal Provisions be applied to documents submitted and published in the IRTF Document Stream following December 28, 2009. Section 4 of these Legal Provisions shall not apply to documents in the IRTF Document Stream, and all references to Section 4 hereof shall be disregarded with respect to documents in the IRTF Document Stream.

+

Section 9. Template Text

+

a. Certain RFCs may contain text designated as “Template Text” by the inclusion of the following legend in the introduction to the RFC:

+

“This RFC contains text intended for use as a template as designated below by the markers <BEGIN TEMPLATE TEXT> and <END TEMPLATE TEXT> or other clear designation. Such Template Text is subject to the provisions of Section 9(b) of the Trust Legal Provisions.”

+

b. In addition to the other rights granted under the TLP with respect to each RFC, the Trust grants to all interested persons a non-exclusive, royalty-free, worldwide, perpetual right and license under all copyrights and rights of authors to insert specific information in place of blanks or place-holders in the Template Text, and to reproduce, publish and distribute the Template Text combined with such insertions.

+

 

+
+ + +
+ +
+ + +
+ + + + +
+ + +
+
+ + + + + + + diff --git a/docs/standards/references/json-ld11-api.html b/docs/standards/references/json-ld11-api.html new file mode 100644 index 0000000..d5a1d40 --- /dev/null +++ b/docs/standards/references/json-ld11-api.html @@ -0,0 +1,8498 @@ + +JSON-LD 1.1 Processing Algorithms and API + + + + + + + + + +
+

JSON-LD 1.1 Processing Algorithms and API

+ +

+ W3C Recommendation + +

+
+
This version:
+ https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/ +
Latest published version:
+ https://www.w3.org/TR/json-ld11-api/ +
+
Latest editor's draft:
https://w3c.github.io/json-ld-api/
+
Test suite:
https://w3c.github.io/json-ld-api/tests/
+
Implementation report:
+ https://w3c.github.io/json-ld-api/reports/ +
+ +
Previous version:
https://www.w3.org/TR/2020/PR-json-ld11-api-20200507/
+
Previous Recommendation:
https://www.w3.org/TR/2014/REC-json-ld-api-20140116/
+
Editors:
+
Gregg Kellogg (v1.0 and v1.1)
Dave Longley + (Digital Bazaar) + (v1.1)
Pierre-Antoine Champin + (LIRIS - Université de Lyon) + (v1.1)
+
+ Former editors: +
Markus Lanthaler + (Google) + (v1.0)
Manu Sporny + (Digital Bazaar) + (v1.0)
+
+ Authors: +
Dave Longley + (Digital Bazaar) + (v1.0 and v1.1)
Gregg Kellogg (v1.0 and v1.1)
Markus Lanthaler + (Google) + (v1.0)
Manu Sporny + (Digital Bazaar) + (v1.0)
Niklas Lindström (v1.0)
+
Participate:
+ GitHub w3c/json-ld-api +
+ File a bug +
+ Commit history +
+ Pull requests +
+
+

+ Please check the + errata for any errors or + issues reported since publication. +

+

+ See also + + translations. +

+

+ This document is also available in this non-normative format: + EPUB +

+

+ Copyright + © + 2010-2020 + + W3C® (MIT, + ERCIM, Keio, + Beihang). + W3C liability, + trademark and permissive document license rules + apply. +

+
+
+

Abstract

+

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.

+ +

This specification describes a superset of the features defined in + JSON-LD 1.0 Processing Algorithms And API [JSON-LD10-API] + and, except where noted, + the algorithms described in this specification are fully compatible + with documents created using JSON-LD 1.0 [JSON-LD10].

+
+ +

Status of This Document

This section describes the status of this + document at the time of its publication. Other documents may supersede + this document. A list of current W3C publications and the latest revision + of this technical report can be found in the + W3C technical reports index at + https://www.w3.org/TR/.

+

This document has been developed by the + JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.

+ +

There is a + live JSON-LD playground that is capable + of demonstrating the features described in this document.

+ +

This specification is intended to supersede the JSON-LD 1.0 Processing Algorithms And API [JSON-LD10-API] specification.

+ + +

+ This document was published by the JSON-LD Working Group as a + Recommendation. + +

+ GitHub Issues are preferred for + discussion of this specification. + + Alternatively, you can send comments to our mailing list. + Please send them to + public-json-ld-wg@w3.org + (archives). + +

+ Please see the Working Group's + implementation report. +

+ This document has been reviewed by W3C Members, by software developers, and + by other W3C groups and interested parties, and is endorsed by the Director + as a W3C Recommendation. It is a stable document and may be used as + reference material or cited from another document. W3C's role in making the + Recommendation is to draw attention to the specification and to promote its + widespread deployment. This enhances the functionality and interoperability + of the Web. +

+ + This document was produced by a group + operating under the + W3C Patent Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + + +

+ This document is governed by the + 1 March 2019 W3C Process Document. +

+

Set of Documents

+

This document is one of three JSON-LD 1.1 Recommendations produced by the + JSON-LD Working Group:

+ + +
+
+ + +
+

1. Introduction

This section is non-normative.

+ +

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

+ +
    +
  • Software developers who want to implement the algorithms to transform + JSON-LD documents.
    • +
  • Web authors and developers who want a very detailed view of how + a JSON-LD Processor operates.
    • +
  • Developers who want an overview of the proposed JSON-LD API.
    • +
+ +

To understand the basics in this specification you must first be familiar with + JSON, which is detailed in [RFC8259]. You must also understand the + JSON-LD syntax defined in the JSON-LD 1.1 Syntax specification [JSON-LD11], which is the base syntax used by all + 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 [ECMASCRIPT] and + WebIDL [WEBIDL]. To understand how JSON-LD maps to RDF, it is helpful to be + familiar with the basic RDF concepts [RDF11-CONCEPTS].

+ +
+

1.1 How to Read this Document

This section is non-normative.

+ +

This document is a detailed specification for a serialization of Linked + Data in JSON. The document is primarily intended for the following audiences:

+ +
    +
  • Software developers who want to implement processors and APIs for + JSON-LD
    • +
+ +

A companion document, the JSON-LD 1.1 specification + [JSON-LD11], specifies the grammar of JSON-LD documents.

+ +

To understand the basics in this specification you must first be familiar with + JSON, which is detailed in [RFC8259].

+ +

This document can highlight changes since the JSON-LD 1.0 version. + Select to changes.

+
+ +
+

1.2 Contributing

This section is non-normative.

+ +

There are a number of ways that one may participate in the development of + this specification:

+ +
    +
  • Technical discussion typically occurs on the public mailing list: + public-json-ld-wg@w3.org
    • + +
  • The working group uses #json-ld + IRC channel is available for real-time discussion on irc.w3.org.
    • + +
  • The #json-ld + IRC channel is also available for real-time discussion on irc.freenode.net.
    • +
+ +
+ +
+

1.3 Typographical conventions

This section is non-normative.

+

The following typographic conventions are used in this specification:

+ +
+
markup
+ Markup (elements, attributes, properties), + machine processable values (string, characters, media types), + property name, + or a file name is in red-orange monospace font.
+
variable
+ A variable in pseudo-code or in an algorithm description is in italics.
+
definition
+ A definition of a term, to be used elsewhere in this or other specifications, + is in bold and italics.
+
definition reference
+ A reference to a definition in this document + is underlined and is also an active link to the definition itself.
+
markup definition reference
+ A references to a definition in this document, + when the reference itself is also a markup, is underlined, + red-orange monospace font, and is also an active link to the definition itself.
+
external definition reference
+ A reference to a definition in another document + is underlined, in italics, and is also an active link to the definition itself.
+
markup external definition reference
+ A reference to a definition in another document, + when the reference itself is also a markup, + is underlined, in italics red-orange monospace font, + and is also an active link to the definition itself.
+
hyperlink
+ A hyperlink is underlined and in blue.
+
[reference]
+ A document reference (normative or informative) is enclosed in square brackets + and links to the references section.
+
Changes from Recommendation
+ Sections or phrases changed from the previous Recommendation + may be highlighted using a control + in § 1.1 How to Read this Document.
+
+ +
Note

Notes are in light green boxes with a green left border and with a "Note" header in green. + Notes are always informative.

+ +
+
+ Example 1 + 
Examples are in light khaki boxes, with khaki left border,
+and with a numbered "Example" header in khaki.
+Examples are always informative. The content of the example is in monospace font and may be syntax colored.
+
+Examples may have tabbed navigation buttons
+to show the results of transforming an example into other representations.
+
+
+
+ +
+

1.4 Terminology

+ +

This document uses the following terms as defined in external specifications + and defines terms specific to JSON-LD.

+ +

Terms imported from Other Specifications

+

Terms imported from ECMAScript Language Specification [ECMASCRIPT], The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], Infra Standard [INFRA], and Web IDL [WEBIDL]

+
array
+ In the JSON serialization, + an array structure is represented as square brackets surrounding zero or more values. + Values are separated by commas. + In the internal representation, + a list (also called an array) is an ordered collection of zero or more values. + While JSON-LD uses the same array representation as JSON, + the collection is unordered by default. + While order is preserved in regular JSON arrays, + it is not in regular JSON-LD arrays unless specifically defined + (see the Sets and Lists section of JSON-LD 1.1.
+
boolean
+ The values true and false that are used + to express one of two possible states.
+
JSON object
+ In the JSON serialization, + an object structure + is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). + A name is a string. + A single colon comes after each name, + separating the name from the value. + A single comma separates a value from a following name. + In JSON-LD the names in an object must be unique. +

In the internal representation a JSON object is described as a + map (see [INFRA]), + composed of entries with key/value pairs.

+

In the Application Programming Interface, + a map is described using a [WEBIDL] record.

+
null
+ The use of the null value within JSON-LD + is used to ignore or reset values. + A map entry in the @context where the value, + or the @id of the value, is null, + explicitly decouples a term's association with an IRI. + A map entry in the body of a JSON-LD document + whose value is null + has the same meaning as if the map entry was not defined. + If @value, @list, or @set is set to null in expanded form, + then the entire JSON object is ignored.
+
number
+ In the JSON serialization, a number + is similar to that used in most programming languages, + except that the octal and hexadecimal formats are not used and that leading zeros are not allowed. + In the internal representation, + a number is equivalent to either a long + or double, + depending on if the number has a non-zero fractional part (see [WEBIDL]).
+
scalar
+ A scalar is either a string, number, true, or false.
+
string
+ A string + is a sequence of zero or more Unicode (UTF-8) characters, + wrapped in double quotes, using backslash escapes (if necessary). + A character is represented as a single character string.
+ +

Terms imported from Internationalized Resource Identifiers (IRIs) [RFC3987]

+
IRI
+ The absolute form of an IRI containing a scheme along with a path + and optional query and fragment segments.
+
IRI reference
+ Denotes the common usage of an Internationalized Resource Identifier. + An IRI reference may be absolute or + relative. + However, the "IRI" that results from such a reference only includes absolute IRIs; + any relative IRI references are resolved to their absolute form.
+
relative IRI reference
+ A relative IRI reference is an IRI reference that is relative to some other IRI, + typically the base IRI of the document. + Note that properties, + values of @type, + and values of terms defined to be vocabulary relative + are resolved relative to the vocabulary mapping, + not the base IRI.
+ +

Terms imported from RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS], RDF Schema 1.1 [RDF-SCHEMA], and Linked Data Design Issues [LINKED-DATA]

+
base IRI
+ The base IRI is an IRI established in the context, + or is based on the JSON-LD document location. + The base IRI is used to turn relative IRI references into IRIs.
+
blank node
+ A node in a graph that is neither an IRI, + nor a literal. + A blank node does not contain + a de-referenceable identifier because it is either ephemeral in nature + or does not contain information that needs to be linked to from outside of the linked data graph. + In JSON-LD, + a blank node is assigned an identifier starting with the prefix _:.
+
blank node identifier
+ A blank node identifier + is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document. + Blank node identifiers begin with _:.
+
dataset
+ A dataset + representing a collection of RDF graphs + including exactly one default graph and zero or more named graphs.
+
datatype IRI
+ A datatype IRI is an IRI identifying a datatype that determines how the lexical form maps to a + literal value.
+
default graph
+ The default graph of a dataset is an RDF graph having no name, which may be empty.
+
graph name
+ The IRI or blank node identifying a named graph.
+
language-tagged string
+ A language-tagged string + consists of a string and a non-empty language tag + as defined by [BCP47]. + The language tag must be well-formed + according to section 2.2.9 Classes of Conformance of [BCP47]. + Processors may normalize language tags to lowercase. +
+
Linked Data
+ A set of documents, each containing a representation of a linked data graph or dataset.
+
list
+ A list is an ordered sequence of IRIs, blank nodes, and literals.
+
literal
+ An object expressed as a value such as a string or number. + Implicitly or explicitly includes a datatype IRI and, if the datatype is rdf:langString, an optional language tag.
+
named graph
+ A named graph + is a linked data graph that is identified by an IRI or blank node.
+
node
+ A node in an RDF graph, either the subject and object of at least one triple. + Note that a node can play both roles (subject and object) in a graph, even in the same triple.
+
object
+ An object is a node in a linked data graph + with at least one incoming edge.
+
property
+ The name of a directed-arc in a linked data graph. + Every property is directional + and is labeled with an IRI or a blank node identifier. + Whenever possible, a property should be labeled with an IRI. +
Note
The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD.
+ Also, see predicate in [RDF11-CONCEPTS].
+
RDF graph
+ A labeled directed graph, + i.e., a set of nodes connected by directed-arcs. + Also called linked data graph. +
+
resource
+ A resource denoted by an IRI, a blank node or literal representing something in the world (the "universe of discourse").
+
subject
+ A subject is a node in a linked data graph + with at least one outgoing edge, + related to an object node through a property.
triple
+ A component of an RDF graph including a subject, predicate, and object, which represents + a node-arc-node segment of an RDF graph.
+
+
+ +

JSON-LD Specific Term Definitions

+
active context
+ A context that is used to resolve terms + while the processing algorithm is running.
+
base direction
+ The base direction is the direction used when a string does not have a direction associated with it directly. + It can be set in the context using the @direction key + whose value must be one of the strings "ltr", "rtl", or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description. +
+ +
compact IRI
+ A compact IRI has the form of prefix:suffix + and is used as a way of expressing an IRI without needing to define separate term definitions + for each IRI contained within a common vocabulary identified by prefix.
+
context
+ A set of rules for interpreting a JSON-LD document + as described in the The Context section of JSON-LD 1.1, + and normatively specified in the Context Definitions section of JSON-LD 1.1. +
+
default language
+ The default language is the language used when a string does not have a language associated with it directly. + It can be set in the context using the @language key + whose value must be a string representing a [BCP47] language code or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description. +
+
default object
+ A default object is a map that has a @default key.
+
expanded term definition
+ An expanded term definition is a term definition + where the value is a map + containing one or more keyword keys to define the associated IRI, + if this is a reverse property, + the type associated with string values, and a container mapping. + See the Expanded Term Definition section of JSON-LD 1.1 for a normative description. +
+
frame
+ A JSON-LD document, + which describes the form for transforming another JSON-LD document + using matching and embedding rules. + A frame document allows additional keywords and certain map entries + to describe the matching and transforming process.
+ +
graph object
+ A graph object represents a named graph + as the value of a map entry within a node object. + When expanded, a graph object must have an @graph entry, + and may also have @id, and @index entries. + A simple graph object + is a graph object which does not have an @id entry. + Note that node objects may have a @graph entry, + but are not considered graph objects if they include any other entries. + A top-level object consisting of @graph is also not a graph object. + Note that a node object may also represent a named graph it it includes other properties. + See the Graph Objects section of JSON-LD 1.1 for a normative description. +
+
id map
+ An id map is a map value of a term + defined with @container set to @id. + The values of the id map must be node objects, + and its keys are interpreted as IRIs representing + the @id of the associated node object. + If a value in the id map contains a key expanding to @id, + its value must be equivalent to the referencing key in the id map. + See the Id Maps section of JSON-LD 1.1 for a normative description. +
+ +
included block
+ An included block is an entry in a node object where the key is either @included or an alias of @included + and the value is one or more node objects. + See the Included Blocks section of JSON-LD 1.1 for a normative description. +
+
index map
+ An index map is a map value of a term + defined with @container set to @index, + whose values must be any of the following types: + string, + number, + true, + false, + null, + node object, + value object, + list object, + set object, or + an array of zero or more of the above possibilities. + See the Index Maps section in JSON-LD 1.1 for a formal description. +
+
JSON literal
+ A JSON literal is a literal where the associated datatype IRI is rdf:JSON. + In the value object representation, the value of @type is @json. + JSON literals represent values which are valid JSON [RFC8259]. + See the The rdf:JSON Datatype section in JSON-LD 1.1 for a normative description. +
+
JSON-LD document
+ A JSON-LD document is a serialization of + an RDF dataset. + See the JSON-LD Grammar section in JSON-LD 1.1 for a formal description. +
+
JSON-LD internal representation
+ The JSON-LD internal representation + is the result of transforming a JSON syntactic structure + into the core data structures suitable for direct processing: + arrays, maps, strings, numbers, booleans, and null.
+
JSON-LD Processor
+ A JSON-LD Processor is a system which can perform the algorithms defined in JSON-LD 1.1 Processing Algorithms and API. + See the Conformance section in JSON-LD 1.1 API for a formal description. +
+
JSON-LD value
+ A JSON-LD value is a string, + a number, + true or false, + a typed value, + or a language-tagged string. + It represents an RDF literal. +
+
keyword
+ A string that is specific to JSON-LD, + described in the Syntax Tokens and Keywords section of JSON-LD 1.1, + and normatively specified in the Keywords section of JSON-LD 1.1, +
+
language map
+ An language map is a map value of a term + defined with @container set to @language, + whose keys must be strings representing [BCP47] language codes + and the values must be any of the following types: + null, + string, or + an array of zero or more of the above possibilities. + See the Language Maps section of JSON-LD 1.1 for a normative description. +
+
list object
+ A list object is a map that has a @list key. + It may also have an @index key, but no other entries. + See the Lists and Sets section of JSON-LD 1.1 for a normative description. +
+
local context
+ A context that is specified with a map, + specified via the @context keyword.
+ +
node object
+ A node object represents zero or more properties of a node in the graph + serialized by the JSON-LD document. + A map is a node object + if it exists outside of the JSON-LD context and: +
    +
  • it does not contain the @value, @list, or @set keywords, or
    • +
  • it is not the top-most map in the JSON-LD document + consisting of no other entries than @graph and @context.
    • +
+ The entries of a node object whose keys are not keywords are also called properties of the node object. + See the Node Objects section of JSON-LD 1.1 for a normative description. +
+ +
prefix
+ A prefix is the first component of a compact IRI + which comes from a term that maps to a string that, + when prepended to the suffix of the compact IRI, + results in an IRI.
+
processing mode
+ The processing mode defines how a JSON-LD document is processed. + By default, all documents are assumed to be conformant with this specification. + By defining a different version using the @version entry in a context, + publishers can ensure that processors conformant with JSON-LD 1.0 [JSON-LD10] + will not accidentally process JSON-LD 1.1 documents, possibly creating a different output. + The API provides an option for setting the processing mode to json-ld-1.0, + which will prevent JSON-LD 1.1 features from being activated, + or error if @version entry in a context is explicitly set to 1.1. + This specification extends JSON-LD 1.0 + via the json-ld-1.1 processing mode.
+
scoped context
+ A scoped context is part of an expanded term definition using the + @context entry. It has the same form as an embedded context. + When the term is used as a type, it defines a type-scoped context, + when used as a property it defines a property-scoped context. +
+
set object
+ A set object is a map that has an @set entry. + It may also have an @index key, but no other entries. + See the Lists and Sets section of JSON-LD 1.1 for a normative description. +
+
term
+ A term is a short word defined in a context + that may be expanded to an IRI. + See the Terms section of JSON-LD 1.1 for a normative description. +
+
term definition
+ A term definition is an entry in a context, + where the key defines a term + which may be used within a map + as a key, type, or elsewhere that a string is interpreted as a vocabulary item. + Its value is either a string (simple term definition), + expanding to an IRI, + or a map (expanded term definition). +
+
type map
+ A type map is a map value of a term + defined with @container set to @type, + whose keys are interpreted as IRIs + representing the @type of the associated node object; + the value must be a node object, or array of node objects. + If the value contains a term expanding to @type, + its values are merged with the map value when expanding. + See the Type Maps section of JSON-LD 1.1 for a normative description. +
+
typed value
+ A typed value consists of a value, + which is a string, + and a type, + which is an IRI.
+
value object
+ A value object is a map that has an @value entry. + See the Value Objects section of JSON-LD 1.1 for a normative description.
+
vocabulary mapping
+ The vocabulary mapping is set in the context using the @vocab key + whose value must be an IRI, a compact IRI, a term, or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description.
+
+
+ +
+

1.4.1 Algorithm Terms

+ +

The Following terms are used within specific algorithms.

+ +
active graph
+ The name of the currently active graph that the processor should use when processing.
+ +
active property
+ The currently active property or keyword that the processor should use when processing. + The active property is represented in the original lexical form, + which is used for finding coercion mappings in the active context.
+ +
add value
+
+ Used as a macro within various algorithms as a way to add a value + to an entry in a map (object) using a specified key. + The invocation may include an as array flag defaulting to false. +
    +
  1. If as array is true + and the value of key in object does not exist + or is not an array, set it to a new array + containing any original value.
    2. +
  2. If value is an array, + then for each element v in value, + use add value recursively to add v to key in entry.
    3. +
  3. Otherwise: +
      +
    1. If key is not an entry in object, + add value as the value of key in object.
      2. +
    2. Otherwise +
        +
      1. If the value of the key entry in object is not an array, + set it to a new array containing the original value.
        2. +
      2. Append value + to the value of the key entry in object.
        3. +
      +
      3. +
    +
    4. +
+
+ + +
IRI compacting
+
+ Used as a macro within various algorithms as to reduce the language used to describe + the process of compacting a string var representing an IRI or keyword + using an active context either specified directly, or coming from the scope of + the algorithm step using this term. + An optional value is used, if explicitly provided. + Unless specified, the vocab flag defaults to true, + and the reverse flag defaults to false. +
    +
  1. Return the result of using the IRI Compaction algorithm, + passing active context, + var, + value (if supplied), + vocab, + and result.
    2. +
+
+
IRI expanding
+
+ Used as a macro within various algorithms as to reduce the language used to describe + the process of expanding a string value representing an IRI or keyword + using an active context either specified directly, or coming from the scope of + the algorithm step using this term. + Optional defined and local context arguments are used, if explicitly provided. + Unless specified, + the document relative flag defaults to false, + and the vocab flag defaults to true. +
    +
  1. Return the result of using the IRI Expansion algorithm, + passing active context, + value, + local context (if supplied), + defined (if supplied), + document relative, + and vocab.
    2. +
+
+ +
JSON-LD input
+ The JSON-LD data structure that is provided as input to the algorithm.
+ + + + + + +
+
+
+
+

1.4.2 Syntax Tokens and Keywords

+ +

In addition to the keywords defined in the JSON-LD 1.1 Syntax specification [JSON-LD11], + this specification adds an additional keyword to support + JSON-LD 1.1 Framing [JSON-LD11-FRAMING]:

+ +
@preserve
+
Used in an expanded document created as the result of the + Framing algorithm + to represent values that might otherwise be removed as part of the + Expansion algorithm.
+
+ +
+ +
+

1.5 Example Conventions

This section is non-normative.

+

Note that in the examples used in this document, output + is of necessity shown in serialized form as JSON. While the algorithms + describe operations on the JSON-LD internal representation, when + they as displayed as examples, the JSON serialization is used. In particular, + the internal representation use of maps are represented using + JSON objects.

+ +
+
+ Example 2: Sample JSON-LD document + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "knows": "http://xmlns.com/foaf/0.1/knows"
+  },
+  "@id": "http://me.markus-lanthaler.com/",
+  "name": "Markus Lanthaler",
+  "knows": [
+    {
+      "name": "Dave Longley"
+    }
+  ]
+}
+
+

In the internal representation, the example above would be of a + map containing @context, @id, name, and knows entries, + with either maps, strings, or arrays of + maps or strings values. In the JSON serialization, JSON objects are used + for maps, while arrays and strings are serialized using a + convention common to many programming languages.

+
+ +
+ + +
+

2. Features

This section is non-normative.

+ +

The JSON-LD 1.1 Syntax specification [JSON-LD11] defines a syntax to + express Linked Data in JSON. Because there is more than one way to + express Linked Data using this syntax, it is often useful to be able to + transform JSON-LD documents so that they may be more easily consumed by + specific applications.

+ +

To allow these algorithms to be adapted for syntaxes + other than JSON, the algorithms operate on the JSON-LD internal representation, + which uses the generic + concepts of arrays, maps, + strings, numbers, booleans, and null to describe + the data represented by a JSON document. Algorithms act on this + internal representation with API entry points responsible for + transforming between the concrete and internal representations.

+ +

JSON-LD uses contexts to allow Linked Data + to be expressed in a way that is specifically tailored to a particular + person or application. By providing a context, + JSON data can be expressed in a way that is a natural fit for a particular + person or application whilst also indicating how the data should be + understood at a global scale. In order for people or applications to + share data that was created using a context that is different + from their own, a JSON-LD processor must be able to transform a document + from one context to another. Instead of requiring JSON-LD + processors to write specific code for every imaginable + context switching scenario, it is much easier to specify a + single algorithm that can remove any context. Similarly, + another algorithm can be specified to subsequently apply any + context. These two algorithms represent the most basic + transformations of JSON-LD documents. They are referred to as + expansion and compaction, respectively.

+ +

JSON-LD 1.1 introduces new features that are + compatible with JSON-LD 1.0 [JSON-LD10], + but if processed by a JSON-LD 1.0 processor may produce different results. + Processors default to json-ld-1.1, unless the + processingMode API option + is explicitly set to json-ld-1.0. + Publishers are encouraged to use the @version map entry within a context + set to 1.1 to ensure that JSON-LD 1.0 processors will not misinterpret JSON-LD 1.1 features.

+ +

There are four major types of transformation that are discussed in this + document: expansion, compaction, flattening, and RDF serialization/deserialization.

+ +
+

2.1 Expansion

This section is non-normative.

+ +

The algorithm that removes context is + called expansion. Before performing any other + transformations on a JSON-LD document, it is easiest to + remove any context from it and to make data structures + more regular.

+ +

To get an idea of how context and data structuring affects the same data, + here is an example of JSON-LD that uses only terms + and is fairly compact:

+ + + +

The next input example uses one IRI to express a property + and a map to encapsulate a value, but + leaves the rest of the information untouched.

+ + + +

Note that both inputs are valid JSON-LD and both represent the same + information. The difference is in their context information + and in the data structures used. A JSON-LD processor can remove + context and ensure that the data is more regular by employing + expansion.

+ +

Expansion has two important goals: removing any contextual + information from the document, and ensuring all values are represented + in a regular form. These goals are accomplished by expanding all entry keys + to IRIs and by expressing all + values in arrays in + expanded form. Expanded form is the most verbose + and regular way of expressing of values in JSON-LD; all contextual + information from the document is instead stored locally with each value. + Running the Expansion algorithm + (expand()) + operation) against the above examples results in the following output:

+ +
+
+ Example 5: Expanded JSON-LD document using an IRI + 
[
+  {
+    "@id": "http://me.markus-lanthaler.com/",
+    "http://xmlns.com/foaf/0.1/name": [
+      { "@value": "Markus Lanthaler" }
+    ],
+    "http://xmlns.com/foaf/0.1/homepage": [
+      { "@id": "http://www.markus-lanthaler.com/" }
+    ]
+  }
+]
+
+ +

The example above is the JSON-LD serialization of the output of the + expansion algorithm, + where the algorithm's use of maps are replaced with JSON objects.

+ +

Note that in the output above all context definitions have + been removed, all terms and + compact IRIs have been expanded to absolute + IRIs, and all + JSON-LD values are expressed in + arrays in expanded form. While the + output is more verbose and difficult for a human to read, it establishes a + baseline that makes JSON-LD processing easier because of its very regular + structure.

+
+ +
+

2.2 Compaction

This section is non-normative.

+ +

While expansion removes context from a given + input, compaction's primary function is to + perform the opposite operation: to express a given input according to + a particular context. Compaction applies a + context that specifically tailors the way information is + expressed for a particular person or application. This simplifies applications + that consume JSON or JSON-LD by expressing the data in application-specific + terms, and it makes the data easier to read by humans.

+ +

Compaction uses a developer-supplied context to + shorten IRIs to terms or + compact IRIs and + JSON-LD values expressed in + expanded form to simple values such as strings + or numbers.

+ +

For example, assume the following expanded JSON-LD input document:

+ +
+
+ Example 6: Expanded sample document + 
[
+  {
+    "@id": "http://me.markus-lanthaler.com/",
+    "http://xmlns.com/foaf/0.1/name": [
+      { "@value": "Markus Lanthaler" }
+    ],
+    "http://xmlns.com/foaf/0.1/homepage": [
+      { "@id": "http://www.markus-lanthaler.com/" }
+    ]
+  }
+]
+
+ +

Additionally, assume the following developer-supplied JSON-LD + context:

+ +
+
+ Example 7: JSON-LD context + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "homepage": {
+      "@id": "http://xmlns.com/foaf/0.1/homepage",
+      "@type": "@id"
+    }
+  }
+}
+
+ +

Running the Compaction Algorithm + (compact()) + operation) given the context supplied above against the JSON-LD input + document provided above would result in the following output:

+ + + +

The example above is the JSON-LD serialization of the output of the + compaction algorithm, + where the algorithm's use of maps are replaced with JSON objects.

+ +

Note that all IRIs have been compacted to + terms as specified in the context, + which has been injected into the output. While compacted output is + useful to humans, it is also used to generate structures that are easy to + program against. Compaction enables developers to map any expanded document + into an application-specific compacted document. While the context provided + above mapped http://xmlns.com/foaf/0.1/name to name, it + could also have been mapped to any other term provided by the developer.

+
+ +
+

2.3 Flattening

This section is non-normative.

+ +

While expansion ensures that a document is in a uniform structure, + flattening goes a step further to ensure that the shape of the data + is deterministic. In expanded documents, the properties of a single + node may be spread across a number of different + node objects. By flattening a + document, all properties of a node are collected in a single + node object and all blank nodes + are labeled with a blank node identifier. This may drastically + simplify the code required to process JSON-LD data in certain applications.

+ +

For example, assume the following JSON-LD input document:

+ +
+
+ Example 9: JSON-LD document in compact form + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "knows": "http://xmlns.com/foaf/0.1/knows"
+  },
+  "@id": "http://me.markus-lanthaler.com/",
+  "name": "Markus Lanthaler",
+  "knows": [
+    {"name": "Dave Longley"}
+  ]
+}
+
+ +

Running the Flattening Algorithm + (flatten()) + operation) with a context set to null to prevent compaction + returns the following document:

+ + + +

The example above is the JSON-LD serialization of the output of the + flattening algorithm, + where the algorithm's use of maps are replaced with JSON objects.

+ +

Note how in the output above all properties of a node are collected in a + single node object and how the blank node representing + "Dave Longley" has been assigned the blank node identifier + _:b0.

+ +

To make it easier for humans to read or for certain applications to + process it, a flattened document can be compacted by passing a context. Using + the same context as the input document, the flattened and compacted document + looks as follows:

+ + + +

Please note that the result of flattening and compacting a document + is always a map, + (represented as a JSON object when serialized), + which contains an @graph + entry that represents the default graph.

+
+ +
+

2.4 RDF Serialization/Deserialization

This section is non-normative.

+ +

JSON-LD can be used to serialize RDF data as described in + [RDF11-CONCEPTS]. This ensures that data can be round-tripped to and from + any RDF syntax without any loss in fidelity.

+ +

For example, assume the following RDF input serialized in Turtle [TURTLE]:

+ +
+
+ Example 12: Sample Turtle document + 
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://me.markus-lanthaler.com/>
+  foaf:name "Markus Lanthaler" ;
+  foaf:homepage <http://www.markus-lanthaler.com/> .
+
+ +

Using the Serialize RDF as JSON-LD Algorithm + a developer could transform this document into expanded JSON-LD:

+ +
+
+ Example 13: Sample Turtle document converted to JSON-LD + 
[
+  {
+    "@id": "http://me.markus-lanthaler.com/",
+    "http://xmlns.com/foaf/0.1/name": [
+      { "@value": "Markus Lanthaler" }
+    ],
+    "http://xmlns.com/foaf/0.1/homepage": [
+      { "@id": "http://www.markus-lanthaler.com/" }
+    ]
+  }
+]
+
+ +

The example above is the JSON-LD serialization of the output of the + Serialize RDF as JSON-LD Algorithm, + where the algorithm's use of maps are replaced with JSON objects.

+ +

Note that the output above could easily be compacted using the technique outlined + in the previous section. It is also possible to deserialize the JSON-LD document back + to RDF using the Deserialize JSON-LD to RDF Algorithm.

+
+
+ + +

3. Conformance

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. +

+ The key words MAY, MUST, MUST NOT, and SHOULD in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+

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

+ +

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

+ +

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

+ +

A conforming RDF Serializer/Deserializer is a system that can + deserialize JSON-LD to RDF and + serialize RDF as JSON-LD as + defined in this specification.

+ +

Unless specified using + processingMode API option, + the processing mode is set using the @version entry + in a local context and + affects the behavior of algorithms including expansion and compaction. + Once set, it is an error to attempt to change to a different processing mode, + and processors MUST generate, + a processing mode conflict + error and abort further processing.

+ +

The algorithms in this specification are generally written with more concern for clarity + 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.

+ +

In algorithm steps that describe operations on keywords, those steps + also apply to keyword aliases.

+ +
Note

Implementers can partially check their level of conformance to + this specification by successfully passing the test cases of the + JSON-LD test suite. + Note, however, that passing all the tests in the test + suite does not imply complete conformance to this specification. It only implies + that the implementation conforms to aspects tested by the test suite.

+ +

This specification makes use of the following namespace prefixes:

+ + + + + + + + + + + + + + + +
PrefixIRI
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#
xsdhttp://www.w3.org/2001/XMLSchema#
+
+ +

4. Context Processing Algorithms

+ +

The following sections describe algorithms for processing a JSON-LD context.

+ +

4.1 Context Processing Algorithm

+ +

When processing a JSON-LD data structure, each processing rule is applied + using information provided by the active context. This + section describes how to produce an active context.

+ +

The active context consists of:

+ + +

Each term definition consists of:

+
    +
  • an IRI mapping (IRI),
    • +
  • a prefix flag (boolean),
    • +
  • a protected flag (boolean),
    • +
  • a reverse property flag (boolean),
    • +
  • an optional base URL (IRI),
    • +
  • an optional context (context),
    • +
  • an optional container mapping (array of strings), +
  • an optional direction mapping ("ltr" or "rtl"),
    • +
  • an optional index mapping (string),
    • +
  • an optional language mapping (string),
    • +
  • an optional nest value (string),
    • +
  • and an optional type mapping (IRI).
    • +
+ +

A term definition can not only be used to map a term + to an IRI, but also to map a term to a keyword, + in which case it is referred to as a keyword alias.

+ +

When processing, active context is initialized + with a null inverse context, + without any term definitions, + vocabulary mapping, default base direction, or default language. + If a local context is encountered during processing, a new + active context is created by cloning the existing + active context. Then the information from the + local context is merged into the new active context. + Given that local contexts may contain + references to remote contexts, this includes their retrieval.

+ +
+

4.1.1 Overview

This section is non-normative.

+ +

First we prepare a new active context result by cloning + the current active context. Then we normalize the form of the original + local context to an array. + Local contexts may be in the form of a + map, a string, or an array containing + a combination of the two. Finally we process each context contained + in the local context array as follows.

+ +

If context is a string, it represents a reference to + a remote context. We dereference the remote context and replace context + with the value of the @context entry of the top-level object in the + retrieved JSON-LD document. + If there's no such entry, an + invalid remote context + has been detected. Otherwise, we process context by recursively using + this algorithm ensuring that there is no cyclical reference.

+ +

If context is a map, + it is a context definition. + We first update + the base IRI, + the default base direction, + the default language, + context propagation, + the processing mode, + and the vocabulary mapping + by processing six specific keywords: + @base, + @direction, + @language, + @propagate, + @version, + and @vocab. + These are handled before any other entries in the local context because + they affect how the other entries are processed. + If context contains @import, it is retrieved and is reverse-merged + into the containing context, allowing JSON-LD 1.0 contexts to be upgraded to JSON-LD 1.1. + Please note that @base is ignored when processing remote contexts.

+ +

If context is not to be propagated, + a reference to the previous context is retained so that + it may be rolled back when a new node object is entered. + By default, all contexts are propagated, other than type-scoped contexts.

+ +

+ When an active context is initialized, the value + of the original base URL + is initialized from the original documentUrl + of the document containing the initial context, if available, + otherwise from the base API option. + This is necessary when resetting the active context + by setting it to null + to retain the original default base IRI.

+ +

When initialized, or when any entry of + an active context is changed, + or any associated term definition is added, changed, or removed, + the inverse context field + in active context is set to null.

+ +

Then, for every other entry in local context, we update + the term definition in result. Since + term definitions in a local context + may themselves contain terms or + compact IRIs, we may need to recurse. + When doing so, we must ensure that there is no cyclical dependency, + which is an error. After we have processed any + term definition dependencies, + we update the current term definition, + which may be a keyword alias.

+ +

Finally, we return result as the new active context.

+
+ +
+

4.1.2 Algorithm

+ +

This algorithm specifies how a new active context is updated + with a local context. The algorithm takes three required + and four optional + input variables. + The required inputs are + an active context, + a local context, + and a base URL used when resolving relative context URLs. + The optional inputs are + an array remote contexts, + defaulting to a new empty array, which is used to detect cyclical context inclusions, + + override protected, defaulting to false, + which is used to allow changes to protected terms, + propagate, defaulting to true + to mark term definitions associated with non-propagated contexts, + and validate scoped context defaulting to true, + which is used to limit recursion when validating possibly recursive scoped contexts.. +

+ +
    +
  1. Initialize result to the result of cloning + active context, + with inverse context set to null..
    2. +
  2. If local context is an object containing the member @propagate, + its value MUST be boolean true or false, + set propagate to that value. +
    Note
    Error handling is performed in step 5.11.
    3. +
  3. If propagate is false, and result + does not have a previous context, set previous context + in result to active context.
    4. +
  4. If local context is not an array, + set local context to an array containing only + local context.
    5. +
  5. + For each item context in local context: +
      +
    1. If context is null: +
        +
      1. If override protected is false and active context + contains any protected term definitions, + an invalid context nullification + has been detected and processing is aborted.
        2. +
      2. Initialize result as a + newly-initialized active context, + + setting both base IRI and original base URL to the value of + original base URL in active context, + and, if propagate is false, + previous context in result + to the previous value of result.
        3. +
      3. Continue with the next context.
        4. +
      +
      2. +
    2. If context is a string, +
        +
      1. Initialize context to the result of resolving context against + base URL. If base URL is not a valid IRI, + then context MUST be a valid IRI, otherwise + a loading document failed error + has been detected and processing is aborted. +
        Note
        + base URL is often not the same as base + or the base IRI of the active context. +
        +
        2. +
      2. If validate scoped context is false, + and remote contexts already includes context + do not process context further and continue to any next + context in local context.
        3. +
      3. If the number of entries in the remote contexts array + exceeds a processor defined limit, a + context overflow + error has been detected and processing is aborted; + otherwise, add context to remote contexts.
        4. +
      4. If context was previously dereferenced, + then the processor MUST NOT do a further dereference, and + context is set to the + previously established internal representation: + set context document to the previously dereferenced document, + and set loaded context to the value of the @context + entry from the document in context document. +
        Note
        Only the @context entry need be retained.
        +
        5. +
      5. Otherwise, set context document + to the RemoteDocument obtained + by dereferencing context using + the LoadDocumentCallback, passing context + for url, + and http://www.w3.org/ns/json-ld#context for profile + and for requestProfile. +
          +
        1. If context cannot be dereferenced, + + or the document from context document + cannot be transformed into the internal representation + , + a loading remote context failed + error has been detected and processing is aborted.
          2. +
        2. If the document has no + top-level map with an @context entry, an + invalid remote context + has been detected and processing is aborted.
          3. +
        3. Set loaded context to the value of that entry.
          4. +
        +
        6. +
      6. Set result to the result of recursively calling this algorithm, + passing result for active context, + loaded context for local context, + + the documentUrl of context document for base URL, + + a copy of remote contexts, + and validate scoped context. +
        Note
        If context was previously dereferenced, + processors MUST make provisions for retaining the base URL + of that context for this step to enable the resolution of any + relative context URLs that may be encountered during processing.
        +
        7. +
      7. Continue with the next context.
        8. +
      +
      3. +
    3. If context is not a map, an + invalid local context + error has been detected and processing is aborted.
      4. +
    4. Otherwise, context is a context definition.
      5. +
    5. If context has an @version entry: +
        +
      1. If the associated value is not 1.1, + an invalid @version value + has been detected, and processing is aborted. +
        Note
        The use of 1.1 for the value of @version is intended to + cause a JSON-LD 1.0 processor to stop processing. + Although it is clearly meant to be related to JSON-LD 1.1, it does not + otherwise adhere to the requirements for Semantic Versioning. + Implementations may require + special consideration + when comparing the values of numbers with a non-zero fractional part.
        +
        2. +
      2. If processing mode + is set to json-ld-1.0, + a processing mode conflict + error has been detected and processing is aborted.
        3. +
      +
      6. +
    6. If context has an @import entry: +
        +
      1. If processing mode is json-ld-1.0, + an invalid context entry + error has been detected and processing is aborted.
        2. +
      2. Otherwise, if the value of @import is not a string, + an invalid @import value + error has been detected and processing is aborted.
        3. +
      3. Initialize import to the result of resolving the value of @import against + base URL.
        4. +
      4. Dereference import using + the LoadDocumentCallback, passing import + for url, + and http://www.w3.org/ns/json-ld#context for profile + and for requestProfile.
        5. +
      5. If import cannot be dereferenced, + or cannot be transformed into the internal representation, + a loading remote context failed + error has been detected and processing is aborted.
        6. +
      6. If the dereferenced document has no + top-level map with an @context entry, + or if the value of @context is not a context definition + (i.e., it is not an map), + an invalid remote context + has been detected and processing is aborted; otherwise, + set import context to the value of that entry.
        7. +
      7. If import context has a @import entry, + an invalid context entry + error has been detected and processing is aborted.
        8. +
      8. Set context to the result of merging context + into import context, replacing common entries + with those from context.
        9. +
      +
      7. +
    7. If context has an @base entry and remote contexts is empty, i.e., the currently + being processed context is not a remote context: +
        +
      1. Initialize value to the value associated with the + @base entry.
        2. +
      2. If value is null, remove the + base IRI of result.
        3. +
      3. Otherwise, if value is an IRI, + the base IRI of result is set to value.
        4. +
      4. Otherwise, if value is a relative IRI reference and + the base IRI of result is not null, + set the base IRI of result to the result of + resolving value against the current base IRI + of result.
        5. +
      5. Otherwise, an + invalid base IRI + error has been detected and processing is aborted.
        6. +
      +
      8. +
    8. If context has an @vocab entry: +
        +
      1. Initialize value to the value associated with the + @vocab entry.
        2. +
      2. If value is null, remove + any vocabulary mapping from result.
        3. +
      3. Otherwise, if value is + an IRI + or blank node identifier, the vocabulary mapping + of result is set to + the result of + IRI expanding value + using true for document relative + . + If it is not an IRI, or a blank node identifier, an + invalid vocab mapping + error has been detected and processing is aborted. +
        Note
        The use of blank node identifiers to value for @vocab is obsolete, + and may be removed in a future version of JSON-LD.
        4. +
      +
      9. +
    9. If context has an @language entry: +
        +
      1. Initialize value to the value associated with the + @language entry.
        2. +
      2. If value is null, remove + any default language from result.
        3. +
      3. Otherwise, if value is a string, the + default language of result is set to + value. + If it is not a string, an + invalid default language + error has been detected and processing is aborted. + If value is not well-formed according to + section 2.2.9 of [BCP47], + processors SHOULD issue a warning. +
        Note
        Processors MAY normalize language tags to lower case.
        +
        4. +
      +
      10. +
    10. If context has an @direction entry: +
        +
      1. If processing mode is json-ld-1.0, + an invalid context entry + error has been detected and processing is aborted.
        2. +
      2. Initialize value to the value associated with the + @direction entry.
        3. +
      3. If value is null, remove + any base direction from result.
        4. +
      4. Otherwise, if value is a string, the + base direction of result is set to + value. If it is not null, "ltr", or "rtl", an + invalid base direction + error has been detected and processing is aborted.
        5. +
      +
      11. +
    11. If context has an @propagate entry: +
        +
      1. If processing mode is json-ld-1.0, + an invalid context entry + error has been detected and processing is aborted.
        2. +
      2. Otherwise, if the value of @propagate is not boolean true or false, + an invalid @propagate value + error has been detected and processing is aborted. +
        Note
        The previous context is actually set earlier in this algorithm; + the previous two steps exist for error checking only.
        +
        3. +
      +
      12. +
    12. Create a map defined to keep + track of whether or not a term has already been defined + or is currently being defined during recursion.
      13. +
    13. For each key-value pair in context where + key is not + @base, + @direction, + @import, + @language, + @propagate, + @protected, + @version, or + @vocab, + invoke the + Create Term Definition algorithm, + passing result for active context, + context for local context, key, + defined, + + base URL, + the value of the @protected + entry from context, if any, for protected, + override protected, + and a copy of remote contexts. + +
      14. +
    +
    6. +
  6. Return result.
    7. +
+
+
+ +

4.2 Create Term Definition

+ +

This algorithm is called from the + Context Processing algorithm + to create a term definition in the active context + for a term being processed in a local context.

+ +
+

4.2.1 Overview

This section is non-normative.

+ +

Term definitions are created by + parsing the information in the given local context for the + given term. If the given term is a + compact IRI, it may omit an IRI mapping by + depending on its prefix having its own + term definition. If the prefix is + an entry in the local context, then its term definition + must first be created, through recursion, before continuing. Because a + term definition can depend on other + term definitions, a mechanism must + be used to detect cyclical dependencies. The solution employed here + uses a map, defined, that keeps track of whether or not a + term has been defined or is currently in the process of + being defined. This map is checked before any recursion is attempted.

+ +

After all dependencies for a term have been defined, the rest of + the information in the local context for the given + term is taken into account, creating the appropriate + IRI mapping, container mapping, and + type mapping, + language mapping, + or direction mapping + for the term.

+
+ +
+

4.2.2 Algorithm

+ +

The algorithm has four required and five optional inputs. + The required inputs are + an active context, + a local context, + a term, + and a map defined. + The optional inputs are + base URL defaulting to null, + protected which defaults to false, + and override protected, defaulting to false, + which is used to allow changes to protected terms, + an array remote contexts, + defaulting to a new empty array, which is used to detect cyclical context inclusions, + and validate scoped context defaulting to true, + which is used to limit recursion when validating possibly recursive scoped contexts.. +

+
    +
  1. If defined contains the entry term and the associated + value is true (indicating that the + term definition has already been created), return. Otherwise, + if the value is false, a + cyclic IRI mapping + error has been detected and processing is aborted.
    2. +
  2. If term is the empty string (""), + an invalid term definition + error has been detected and processing is aborted. + Otherwise, set the value associated with defined's term entry to + false. This indicates that the term definition + is now being created but is not yet complete.
    3. +
  3. Initialize value to a copy of the value associated with the entry + term in local context.
    4. +
  4. If term is @type, + and processing mode is json-ld-1.0, + a keyword redefinition error has + been detected and processing is aborted. + At this point, + value MUST be a map with only either or both of the following entries: +
      +
    • An entry for @container with value @set.
      • +
    • An entry for @protected.
      • +
    + Any other value means that a + keyword redefinition error has + been detected and processing is aborted.
    5. +
  5. Otherwise, since keywords cannot be overridden, + term MUST NOT be a keyword and a + keyword redefinition + error has been detected and processing is aborted. + If term has the form of a keyword + (i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]), + return; processors SHOULD generate a warning.
    6. +
  6. Initialize previous definition to any existing + term definition for term in active context, + removing that term definition from active context.
    7. +
  7. If value is null, + convert it to a map consisting of a single entry whose + key is @id and whose value is null.
    8. +
  8. Otherwise, if value is a string, convert it + to a map consisting of a single entry whose + key is @id and whose value is value. + Set simple term to true.
    9. +
  9. Otherwise, value MUST be a map, if not, an + invalid term definition + error has been detected and processing is aborted. + Set simple term to false.
    10. +
  10. Create a new term definition, definition, + initializing prefix flag to false, + protected to protected, + and reverse property to false.
    11. +
  11. If value has an @protected entry, + set the protected flag in definition to the value of this entry. + If the value of @protected is not a boolean, + an invalid @protected value error has been detected and processing is aborted. + If processing mode is json-ld-1.0, + an invalid term definition + has been detected and processing is aborted.
    12. +
  12. If value contains the entry @type: +
      +
    1. Initialize type to the value associated with the + @type entry, which MUST be a string. Otherwise, an + invalid type mapping + error has been detected and processing is aborted.
      2. +
    2. Set type to the result of + IRI expanding type, + using local context, and defined.
      3. +
    3. If the expanded type is + @json or @none, and processing mode is json-ld-1.0, + an invalid type mapping + error has been detected and processing is aborted.
      4. +
    4. Otherwise, if the expanded type is + neither @id, nor @json, + nor @none, + nor @vocab, + nor an IRI, + an invalid type mapping + error has been detected and processing is aborted.
      5. +
    5. Set the type mapping for definition to type.
      6. +
    +
    13. +
  13. If value contains the entry @reverse: +
      +
    1. If value contains @id or @nest, entries, an + invalid reverse property + error has been detected and processing is aborted.
      2. +
    2. If the value associated with the @reverse entry + is not a string, an + invalid IRI mapping + error has been detected and processing is aborted.
      3. +
    3. If the value associated with the @reverse entry is a string + having the form of a keyword + (i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]), + return; processors SHOULD generate a warning.
      4. +
    4. Otherwise, set the IRI mapping of definition to the + result of + IRI expanding + the value associated with the @reverse entry, + using local context, and defined. + If the result does not have the form of an IRI or a blank node identifier, + an invalid IRI mapping + error has been detected and processing is aborted.
      5. +
    5. If value contains an @container entry, + set the container mapping of definition + to an array containing its value; + if its value is neither @set, nor + @index, nor null, an + invalid reverse property + error has been detected (reverse properties only support set- and + index-containers) and processing is aborted.
      6. +
    6. Set the reverse property flag of definition + to true.
      7. +
    7. Set the term definition of term in + active context to definition and the + value associated with defined's entry term to + true and return.
      8. +
    +
    14. +
  14. If value contains the entry @id and its value + does not equal term: +
      +
    1. If the @id entry of value + is null, the term is not used for IRI expansion, but is + retained to be able to detect future redefinitions of this term.
      2. +
    2. Otherwise: +
        +
      1. If the value associated with the @id entry is not a string, an + invalid IRI mapping + error has been detected and processing is aborted.
        2. +
      2. If the value associated with the @id entry + is not a keyword, but + has the form of a keyword + (i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]), + return; processors SHOULD generate a warning.
        3. +
      3. Otherwise, set the IRI mapping of definition to the + result of + IRI expanding + the value associated with the @id entry, + using local context, and defined. + If the resulting IRI mapping is neither a keyword, nor an + IRI, nor a blank node identifier, an + invalid IRI mapping + error has been detected and processing is aborted; if it equals @context, an + invalid keyword alias + error has been detected and processing is aborted.
        4. +
      4. If the term contains a colon (:) + anywhere but as the first or last character of term, + or if it contains a slash (/) anywhere: +
          +
        1. Set the value associated with defined's term entry to + true.
          2. +
        2. If the result of IRI expanding term + using local context, and defined, + is not the same as the IRI mapping of definition, + an invalid IRI mapping + error has been detected and processing is aborted.
          3. +
        +
        5. +
      5. If term contains neither a colon (:) nor a slash (/), + simple term is true, + and if the IRI mapping of definition + is either an IRI ending with a gen-delim character, + or a blank node identifier, + set the prefix flag in definition to true.
        6. +
      +
      3. +
    +
    15. +
  15. + Otherwise if the term contains a colon (:) + anywhere after the first character: +
      +
    1. If term is a compact IRI with a + prefix that is an entry in local context + a dependency has been found. Use this algorithm recursively passing + active context, local context, the + prefix as term, and defined.
      2. +
    2. If term's prefix has a + term definition in active context, set + the IRI mapping of definition to the result of + concatenating the value associated with the prefix's + IRI mapping and the term's suffix.
      3. +
    3. Otherwise, term is an IRI or + blank node identifier. Set the IRI mapping + of definition to term.
      4. +
    +
    16. +
  16. + Otherwise if the term contains a slash (/): +
      +
    1. Term is a relative IRI reference.
      2. +
    2. Set the IRI mapping of definition to the + result of IRI expanding term. + If the resulting IRI mapping is not an IRI, an + invalid IRI mapping + error has been detected and processing is aborted.
      3. +
    +
    17. +
  17. Otherwise, if term is @type, set the IRI mapping + of definition to @type.
    18. +
  18. Otherwise, if active context has a + vocabulary mapping, the IRI mapping + of definition is set to the result of concatenating the value + associated with the vocabulary mapping and term. + If it does not have a vocabulary mapping, an + invalid IRI mapping + error been detected and processing is aborted.
    19. +
  19. If value contains the entry @container: +
      +
    1. Initialize container to the value associated with the + @container entry, which MUST be either + @graph, + @id, + @index, + @language, + @list, + @set, + @type, + + or an array containing exactly any one of those keywords, + an array containing @graph and + either @id or @index optionally + including @set, + or an array containing a combination of @set and any of + @index, @graph, + @id, @type, + @language in any order + . + Otherwise, an + invalid container mapping + has been detected and processing is aborted.
      2. +
    2. If the container value + is @graph, @id, or @type, or is otherwise not a string, + generate an invalid container mapping + error and abort processing if processing mode is json-ld-1.0.
      3. +
    3. Set the container mapping of definition to + container + coercing to an array, if necessary.
      4. +
    4. If the container mapping of definition includes @type: +
        +
      1. If type mapping in definition is undefined, set it to @id.
        2. +
      2. If type mapping in definition is neither @id nor @vocab, + an invalid type mapping + error has been detected and processing is aborted.
        3. +
      +
      5. +
    +
    20. +
  20. If value contains the entry @index: +
      +
    1. If processing mode is json-ld-1.0 or + container mapping does not include @index, + an invalid term definition + has been detected and processing is aborted.
      2. +
    2. Initialize index to the value associated with the + @index entry. + If the result of IRI expanding that value is not an IRI, + an + invalid term definition + has been detected and processing is aborted.
      3. +
    3. Set the index mapping of definition to index
      4. +
    +
    21. +
  21. If value contains the entry @context: +
      +
    1. If processing mode is json-ld-1.0, an + invalid term definition + has been detected and processing is aborted.
      2. +
    2. Initialize context to the value associated with the + @context entry, which is treated as a local context.
      3. +
    3. Invoke the Context Processing algorithm + using the active context, context as local context, + base URL, + true for override protected, + a copy of remote contexts, + and false for validate scoped context. + If any error is detected, an + invalid scoped context error + has been detected and processing is aborted. +
      Note

      The result of the Context Processing algorithm + is discarded; it is called to detect errors at definition time. + If used, the context will be re-processed and applied to the active context + as part of expansion or compaction.

      4. +
    4. Set the local context of definition to context, + and base URL to base URL.
      5. +
    +
    22. +
  22. If value contains the entry @language and + does not contain the entry @type: +
      +
    1. Initialize language to the value associated with the + @language entry, which MUST be either null + or a string. + If language is not well-formed according to + section 2.2.9 of [BCP47], + processors SHOULD issue a warning. + Otherwise, an invalid language mapping + error has been detected and processing is aborted.
      2. +
    2. Set the language mapping of definition to language. +
      Note
      Processors MAY normalize language tags to lower case.
      +
      3. +
    +
    23. +
  23. If value contains the entry @direction and + does not contain the entry @type: +
      +
    1. Initialize direction to the value associated with the + @direction entry, which MUST be either null, + "ltr", or "rtl". Otherwise, an + invalid base direction + error has been detected and processing is aborted.
      2. +
    2. Set the direction mapping + of definition to direction.
      3. +
    +
    24. +
  24. If value contains the entry @nest: +
      +
    1. If processing mode is json-ld-1.0, an + invalid term definition + has been detected and processing is aborted.
      2. +
    2. Initialize nest value in definition to the value associated with the + @nest entry, which MUST be a string and + MUST NOT be a keyword other than @nest. Otherwise, an + invalid @nest value + error has been detected and processing is aborted.
      3. +
    +
    25. +
  25. If value contains the entry @prefix: +
      +
    1. If processing mode is json-ld-1.0, or if + term contains a colon (:) or slash (/), an + invalid term definition + has been detected and processing is aborted.
      2. +
    2. Set the prefix flag to the value associated with the + @prefix entry, which MUST be a boolean. Otherwise, an + invalid @prefix value + error has been detected and processing is aborted.
      3. +
    3. If the prefix flag of definition is set to true, + and its IRI mapping is a keyword, + an invalid term definition + has been detected and processing is aborted.
      4. +
    +
    26. +
  26. If value contains any entry other than @id, + @reverse, @container, + @context, + @direction, + @index, + @language, + @nest, + @prefix, + @protected, + or @type, + an invalid term definition error has + been detected and processing is aborted.
    27. +
  27. If override protected is false + and previous definition exists and is protected; +
      +
    1. If definition is not the same as previous definition + (other than the value of protected), + a protected term redefinition error has been detected, + and processing is aborted.
      2. +
    2. Set definition to previous definition to retain the value + of protected.
      3. +
    +
    28. +
  28. Set the term definition of term in + active context to definition and set the value + associated with defined's entry term to + true.
    29. +
+
+
+ +

4.3 Inverse Context Creation

+ +

When there is more than one term that could be chosen + to compact an IRI, it has to be ensured that the term + selection is both deterministic and represents the most context-appropriate + choice whilst taking into consideration algorithmic complexity.

+ +

In order to make term selections, the concept of an + inverse context is introduced. An inverse context + is essentially a reverse lookup table that maps + container mapping, + type mappings, and + language mappings to a simple + term for a given active context. A + inverse context only needs to be generated for an + active context if it is being used for compaction.

+ +

To make use of an inverse context, a list of preferred + container mapping and the + type mapping or language mapping are gathered + for a particular value associated with an IRI. These parameters + are then fed to the Term Selection algorithm, + which will find the term that most appropriately + matches the value's mappings.

+ +
+

4.3.1 Overview

This section is non-normative.

+ +

To create an inverse context for a given + active context, each term in the + active context is visited, ordered by length, shortest + first (ties are broken by choosing the lexicographically least + term). For each term, an entry is added to + the inverse context for each possible combination of + container mapping and type mapping + or language mapping that would legally match the + term. Illegal matches include differences between a + value's type mapping or language mapping and + that of the term. If a term has no + container mapping, type mapping, or + language mapping (or some combination of these), then it + will have an entry in the inverse context using the special + key @none. This allows the + Term Selection algorithm to fall back + to choosing more generic terms when a more + specifically-matching term is not available for a particular + IRI and value combination.

+ +

Although normalizing language tags is optional, + the inverse context creates entries based on normalized + language tags, so that the proper term can be selected + regardless of representation.

+
+ +
+

4.3.2 Algorithm

+ +

The algorithm takes one required input: the active context that + the inverse context is being created for.

+ +
    +
  1. Initialize result to an empty map.
    2. +
  2. Initialize default language to @none. + If the active context has a default language, + set default language to the default language from the active context + normalized to lower case.
    3. +
  3. For each key term and value term definition in + the active context, ordered by shortest term + first (breaking ties by choosing the lexicographically least + term): +
      +
    1. If the term definition is null, + term cannot be selected during compaction, + so continue to the next term.
      2. +
    2. Initialize container to @none. + + If the container mapping is not empty, set container + to the concatenation of all values of the container mapping + in lexicographical order + .
      3. +
    3. Initialize var to the value of the IRI mapping + for the term definition.
      4. +
    4. If var is not an entry of result, add + an entry where the key is var and the value + is an empty map to result.
      5. +
    5. Reference the value associated with the var entry in + result using the variable container map.
      6. +
    6. If container map has no container entry, + create one and set its value to a new + map with three entries. + The first entry is @language and its value is a new empty + map, the second entry is @type + and its value is a new empty map, + and the third entry is @any + and its value is a new map with the entry + @none set to the term being processed.
      7. +
    7. Reference the value associated with the container entry + in container map using the variable type/language map.
      8. +
    8. Reference the value associated with the @type + entry in type/language map using the variable + type map.
      9. +
    9. Reference the value associated with the @language + entry in type/language map using the variable + language map.
      10. +
    10. If the term definition indicates that the term + represents a reverse property: +
        +
      1. If type map does not have an @reverse + entry, create one and set its value to the term + being processed.
        2. +
      +
      11. +
    11. Otherwise, if term definition has a + type mapping which is @none: +
        +
      1. If language map does not have an @any + entry, create one and set its value to the term + being processed.
        2. +
      2. If type map does not have an @any + entry, create one and set its value to the term + being processed.
        3. +
      +
      12. +
    12. Otherwise, if term definition has a + type mapping: +
        +
      1. If type map does not have an entry corresponding + to the type mapping in term definition, + create one and set its value to the term + being processed.
        2. +
      +
      13. +
    13. Otherwise, if term definition has both + a language mapping and a direction mapping: +
        +
      1. Create a new variable lang dir.
        2. +
      2. If neither the language mapping nor the direction mapping + are null, set lang dir to the concatenation + of language mapping and direction mapping + separated by an underscore ("_") + normalized to lower case.
        3. +
      3. Otherwise, if language mapping is not null, + set lang dir to the language mapping, + normalized to lower case. +
      4. Otherwise, if direction mapping is not null, + set lang dir to direction mapping + preceded by an underscore ("_").
        5. +
      5. Otherwise, set lang dir to @null.
        6. +
      6. If language map does not have a lang dir + entry, create one and set its value to the term + being processed.
        7. +
      +
      14. +
    14. Otherwise, if term definition has a + language mapping (might be null): +
        +
      1. If the language mapping equals null, + set language to @null; otherwise + to the language mapping, + normalized to lower case.
        2. +
      2. If language map does not have a language entry, + create one and set its value to the term + being processed.
        3. +
      +
      15. +
    15. Otherwise, if term definition has a + direction mapping (might be null): +
        +
      1. If the direction mapping equals null, + set direction to @none; otherwise + to direction mapping preceded by an underscore ("_").
        2. +
      2. If language map does not have a direction entry, + create one and set its value to the term + being processed.
        3. +
      +
      16. +
    16. Otherwise, if active context has a + default base direction: +
        +
      1. Initialize a variable lang dir + with the concatenation of default language and default base direction, + separate by an underscore ("_"), + normalized to lower case.
        2. +
      2. If language map does not have a lang dir entry, + create one and set its value to the term + being processed.
        3. +
      3. If language map does not have an @none entry, + create one and set its value to the term + being processed.
        4. +
      4. If type map does not have an @none entry, + create one and set its value to the term + being processed.
        5. +
      +
      17. +
    17. Otherwise: +
        +
      1. If language map does not have a default language entry + (after being normalized to lower case), + create one and set its value to the term + being processed.
        2. +
      2. If language map does not have an @none + entry, create one and set its value to the term + being processed.
        3. +
      3. If type map does not have an @none + entry, create one and set its value to the term + being processed.
        4. +
      +
      18. +
    +
    4. +
  4. Return result.
    5. +
+
+
+ +

4.4 Term Selection

+ +

This algorithm, invoked via the IRI Compaction algorithm, + makes use of an active context's + inverse context to find the term that is best + used to compact an IRI. Other + information about a value associated with the IRI is given, + including which container mapping + and which type mapping or language mapping would + be best used to express the value.

+ +
+

4.4.1 Overview

This section is non-normative.

+ +

The inverse context's entry for + the IRI will be first searched according to the preferred + container mapping, in the order + that they are given. Amongst terms with a matching + container mapping, preference will be given to those + with a matching type mapping or language mapping, + over those without a type mapping or + language mapping. If there is no term + with a matching container mapping then the term + without a container mapping that matches the given + type mapping or language mapping is selected. If + there is still no selected term, then a term + with no type mapping or language mapping will + be selected if available. No term will be selected that + has a conflicting type mapping or language mapping. + Ties between terms that have the same + mappings are resolved by first choosing the shortest terms, and then by + choosing the lexicographically least term. Note that these ties are + resolved automatically because they were previously resolved when the + Inverse Context Creation algorithm + was used to create the inverse context.

+
+ +
+

4.4.2 Algorithm

+ +

This algorithm has five required inputs. They are: + an active context, + a keyword or IRI var, + an array containers that represents an + ordered list of preferred container mapping, + a string type/language that indicates whether + to look for a term with a matching type mapping + or language mapping, + and an array representing an ordered list of preferred values + for the type mapping or language mapping to look for.

+ +
    +
  1. If the active context has a null + inverse context, + set inverse context in active context + to the result of calling the + Inverse Context Creation algorithm + using active context.
    2. +
  2. Initialize inverse context to the value of + inverse context in active context.
    3. +
  3. Initialize container map to the value associated with + var in the inverse context.
    4. +
  4. For each item container in containers: +
      +
    1. If container is not an entry of container map, then + there is no term with a matching + container mapping for it, so continue to the next + container.
      2. +
    2. Initialize type/language map to the value associated + with the container entry in container map.
      3. +
    3. Initialize value map to the value associated + with type/language entry in type/language map.
      4. +
    4. For each item in preferred values: +
        +
      1. If item is not an entry of value map, + then there is no term with a matching + type mapping or language mapping, + so continue to the next item.
        2. +
      2. Otherwise, a matching term has been found, return the value + associated with the item entry in + value map.
        3. +
      +
      5. +
    +
    5. +
  5. No matching term has been found. Return null.
    6. +
+
+ +
+

4.4.3 Examples

This section is non-normative.

+

The following examples are intended to illustrate how the term selection algorithm + behaves for different term definitions and values. It is not comprehensive, but + intended to illustrate different parts of the algorithm.

+ +
+
Language Map Term
+

If the term definition has "@container": "@language", it will only match a + value object having no @type.

+ + + + +
+ +
+
Datatyped Term
+

If the term definition has a datatype, it will only match a + value object having a matching datatype.

+ + + + + + + + +
+
+
+
+ +

5. Expansion Algorithms

+ +

The following sections describe algorithms for expanding JSON-LD + documents, IRIs and values.

+ +

5.1 Expansion Algorithm

+ +

This algorithm expands a JSON-LD document, such that all context + definitions are removed, all terms and + compact IRIs are expanded to + IRIs, + blank node identifiers, or + keywords and all + JSON-LD values are expressed in + arrays in expanded form.

+ +
+

5.1.1 Overview

This section is non-normative.

+ +

Starting with its root element, we can process the + JSON-LD document recursively, until we have a fully + expanded result. When + expanding an element, we can treat + each one differently according to its type, in order to break down the + problem:

+ +
    +
  1. If the element is null, there is nothing + to expand.
    2. +
  2. Otherwise, if element is a scalar, we expand it + according to the Value Expansion algorithm.
    3. +
  3. Otherwise, if the element is an array, then we expand + each of its items recursively and return them in a new + array.
    4. +
  4. Otherwise, element is a map. We expand + each of its entries, adding them to our result, and then we expand + each value for each entry recursively. Some of the entry keys will be + terms or + compact IRIs and others will be + keywords or simply ignored because + they do not have definitions in the context. Any + IRIs will be expanded using the + IRI Expansion algorithm. +
    5. +
+ +

Finally, after ensuring result is in an array, + we return result.

+ +
Note

Although the data model, + based on [RDF11-CONCEPTS], does not support multiple unordered property values, + this algorithm does not remove duplicates that + may be found during expansion within an unordered array. + Other algorithms, such as § 6.1 Compaction Algorithm, + and § 7.1 Flattening Algorithm, do eliminate + duplicate values from unordered arrays. + A future version of this specification may be updated to remove duplicate + array values when the form a set.

+
+ +
+

5.1.2 Algorithm

+ +

The algorithm takes four required and three optional input variables. + The required inputs are an active context, + an active property, an element to be expanded, + and a base URL associated with the documentUrl of the original + document to expand. + The optional inputs are the + frameExpansion + flag allowing special forms of input used for frame expansion, + the ordered flag, used to order + map entry keys lexicographically, where noted, + and the from map flag, used to control reverting + previous term definitions in the active context associated with non-propagated contexts. + If not passed, the optional flags are set to false.

+ +

The algorithm also performs processing steps specific to expanding + a JSON-LD Frame. For a frame, the @id and + @type entries can accept an array of IRIs or + an empty map. The entries of a value object can also + accept an array of strings, or an empty map. + Framing also uses additional keyword entries: + (@explicit, @default, + @embed, @explicit, @omitDefault, or + @requireAll) which are preserved through expansion. + Special processing for a JSON-LD Frame is invoked when the + frameExpansion flag is set to true.

+ +
Note

As mentioned in Terms [JSON-LD11], + to avoid forward-compatibility issues, terms should not start with an + @ character as future versions of JSON-LD may introduce + additional keywords. + This algorithm will treat such terms like any other term, i.e., they are ignored unless mapped to an IRI. + Implementations of this algorithm may consider providing a + runtime flag to show a warning if such terms are encountered.

+ +
Note

The use of empty terms ("") is not + allowed as not all programming languages are able to handle empty JSON keys. + Implementations of this algorithm may consider providing a + runtime flag to show a warning if such terms are encountered.

+ +
Note

The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD. + Implementations of this algorithm may consider providing a + runtime flag to show a warning if such terms are encountered.

+ +
    +
  1. If element is null, return null.
    2. +
  2. If active property is @default, + initialize the frameExpansion flag to false.
    3. +
  3. If active property has a term definition in active context + with a local context, initialize property-scoped context to that local context.
    4. +
  4. If element is a scalar, +
      +
    1. If active property is null or @graph, + drop the free-floating scalar by returning null.
      2. +
    2. If property-scoped context is defined, + set active context to the result of the + Context Processing algorithm, + passing active context, property-scoped context as local context, + and base URL from the term definition for active property + in active context.
      3. +
    3. Return the result of the + Value Expansion algorithm, passing the + active context, active property, and + element as value.
      4. +
    +
    5. +
  5. If element is an array, +
      +
    1. Initialize an empty array, result.
      2. +
    2. For each item in element: +
        +
      1. Initialize expanded item to the result of using this + algorithm recursively, passing active context, + active property, item as element, + base URL, + the frameExpansion + ordered, + and from map flags.
        2. +
      2. If the container mapping + of active property includes @list, + and expanded item is an + array, set expanded item to a new + map containing the entry + @list where the value is the original + expanded item.
        3. +
      3. If expanded item is an array, append each + of its items to result. Otherwise, if + expanded item is not null, append it to result.
        4. +
      +
      3. +
    3. Return result.
      4. +
    +
    6. +
  6. Otherwise element is a map.
    7. +
  7. If active context has a previous context, + the active context is not propagated. + If from map is undefined or false, + and element does not contain an entry expanding to @value, + and element does not consist of a single entry expanding to @id + (where entries are IRI expanded, + set active context to previous context from active context, + as the scope of a term-scoped context does not apply when processing new node objects.
    8. +
  8. If property-scoped context is defined, + set active context to the result of the + Context Processing algorithm, + passing active context, property-scoped context as local context, + base URL from the term definition for active property, + in active context + and true for override protected.
    9. +
  9. If element contains the entry @context, set + active context to the result of the + Context Processing algorithm, + passing active context, the value of the + @context entry as local context + and base URL.
    10. +
  10. Initialize type-scoped context to active context. + This is used for expanding values that may be relevant to any previous + type-scoped context.
    11. +
  11. For each key and value in element + ordered lexicographically by key + where key IRI expands to @type: +
      +
    1. Convert value into an array, if necessary.
      2. +
    2. For each term which is a value of value ordered lexicographically, + if term is a string, + and term's term definition in type-scoped context + has a local context, set active context to the result + Context Processing algorithm, + passing active context, + the value of the + term's local context as local context, + base URL from the term definition for value + in active context, + and false for propagate.
      3. +
    +
    12. +
  12. Initialize two empty maps, result + and nests. + Initialize input type to expansion of the last value of the first entry in element + expanding to @type (if any), ordering entries lexicographically by key. + Both the key and value of the matched entry are + IRI expanded. +
    13. +
  13. + For each key and value in element, + ordered lexicographically by key if ordered is true: +
      +
    1. If key is @context, continue to + the next key.
      2. +
    2. Initialize expanded property to the result of + IRI expanding key.
      3. +
    3. If expanded property is null or it neither + contains a colon (:) nor it is a keyword, + drop key by continuing to the next key.
      4. +
    4. If expanded property is a keyword: +
        +
      1. If active property equals @reverse, an + invalid reverse property map + error has been detected and processing is aborted.
        2. +
      2. If result already has an expanded property entry, + other than @included or @type + (unless processing mode is json-ld-1.0), + a colliding keywords + error has been detected and processing is aborted.
        3. +
      3. If expanded property is @id: +
          +
        1. If value is not a string, an + invalid @id value + error has been detected and processing is aborted. + + When the frameExpansion flag is set, value + MAY be an empty map, or an array of one + or more strings.
          2. +
        2. Otherwise, + set expanded value to the result of + IRI expanding value + using true for document relative + and false for vocab. + + When the frameExpansion flag is set, expanded value will be + an array of one or more of the values, with string + values expanded using the IRI Expansion algorithm as above.
          3. +
        +
        4. +
      4. If expanded property is @type: +
          +
        1. If value + is neither a string nor an array of + strings, an + invalid type value + error has been detected and processing is aborted. + + When the frameExpansion flag is set, value + MAY be an empty map, or a default object + where the value of @default is restricted to be + an IRI. + All other values mean that invalid type value + error has been detected and processing is aborted.
          2. +
        2. If value + is an empty map, set expanded value to value.
          3. +
        3. Otherwise, if value + is a default object, set expanded value to + a new default object with the value of @default set + to the result of + IRI expanding value + using type-scoped context for active context, + and true for document relative.
          4. +
        4. Otherwise, + set expanded value to the result of + IRI expanding + each of its values + using type-scoped context for active context, + and true for document relative. +
          5. +
        5. If result already has an entry for @type, + prepend the value of @type in result to expanded value, + transforming it into an array, if necessary. +
          Note
          + No transformation from a string value to an array + expanded value is implied, and the form or value + should be preserved in expanded value. +
          6. +
        +
        5. +
      5. If expanded property is @graph, set + expanded value to the result of using this algorithm + recursively passing active context, @graph + for active property, value for element, + base URL, + and the frameExpansion + and ordered flags, + + ensuring that expanded value is an array of one or more maps.
        6. +
      6. If expanded property is @included: +
          +
        1. If processing mode is json-ld-1.0, + continue with the next key from element.
          2. +
        2. Set expanded value to the result of using + this algorithm recursively passing active context, + null for active property, + value for element, + base URL, + and the frameExpansion + and ordered flags, + ensuring that the result is an array.
          3. +
        3. If any element of expanded value is not a node object, + an invalid @included value + error has been detected and processing is aborted.
          4. +
        4. If result already has an entry for @included, + prepend the value of @included in result to expanded value.
          5. +
        +
        7. +
      7. If expanded property is @value: +
          +
        1. If + input type is @json, + set expanded value to value. + If processing mode is json-ld-1.0, + an invalid value object value + error has been detected and processing is aborted.
          2. +
        2. Otherwise, if value is not a scalar or null, + an invalid value object value + error has been detected and processing is aborted. + When the frameExpansion flag is set, value + MAY be an empty map or an array of + scalar values.
          3. +
        3. Otherwise, set expanded value to value. + When the frameExpansion flag is set, + expanded value will be an + array of one or more string values + or an array containing an empty map. +
          4. +
        4. If expanded value + is null, set the @value + entry of result to null and continue with the + next key from element. Null values need to be preserved + in this case as the meaning of an @type entry depends + on the existence of an @value entry.
          5. +
        +
        8. +
      8. If expanded property is @language: +
          +
        1. If value is not a string, an + invalid language-tagged string + error has been detected and processing is aborted. + When the frameExpansion flag is set, value + MAY be an empty map or an array of zero or more + strings.
          2. +
        2. + Otherwise, set expanded value to value. + If value is not well-formed according to + section 2.2.9 of [BCP47], + processors SHOULD issue a warning. + When the frameExpansion flag is set, + expanded value will be an + array of one or more string values + or an array containing an empty map. +
          Note
          Processors MAY normalize language tags to lower case.
          +
          3. +
        +
        9. +
      9. If expanded property is @direction: +
          +
        1. If processing mode is json-ld-1.0, + continue with the next key from element.
          2. +
        2. If value is neither "ltr" nor "rtl", an + invalid base direction + error has been detected and processing is aborted. + When the frameExpansion flag is set, value + MAY be an empty map or an array of zero or more + strings.
          3. +
        3. Otherwise, set expanded value to value. + When the frameExpansion flag is set, + expanded value will be an + array of one or more string values + or an array containing an empty map.
          4. +
        +
        10. +
      10. If expanded property is @index: +
          +
        1. If value is not a string, an + invalid @index value + error has been detected and processing is aborted.
          2. +
        2. Otherwise, + set expanded value to value.
          3. +
        +
        11. +
      11. If expanded property is @list: +
          +
        1. If active property is null or + @graph, continue with the next key + from element to remove the free-floating list.
          2. +
        2. Otherwise, initialize expanded value to the result of using + this algorithm recursively passing active context, + active property, value for element, + base URL, + and the frameExpansion + and ordered flags, + ensuring that the result is an array..
          3. +
        +
        12. +
      12. If expanded property is @set, set + expanded value to the result of using this algorithm + recursively, passing active context, + active property, value for element, + base URL, + and the frameExpansion + and ordered flags.
        13. +
      13. If expanded property is @reverse: +
          +
        1. If value is not a map, an + invalid @reverse value + error has been detected and processing is aborted.
          2. +
        2. Otherwise initialize expanded value to the result of using this + algorithm recursively, passing active context, + @reverse as active property, + value as element, + base URL, + and the frameExpansion + and ordered flags.
          3. +
        3. If expanded value contains an @reverse entry, + i.e., properties that are reversed twice, execute for each of its + property and item the following steps: +
            +
          1. Use add value to add item + to the property entry in result + using true for as array.
            2. +
          +
          4. +
        4. If expanded value contains an entry other than @reverse: +
            +
          1. Set reverse map to the value + of the @reverse entry in result, + initializing it to an empty map, if necessary.
            2. +
          2. For each property and items in expanded value + other than @reverse: +
              +
            1. For each item in items: +
                +
              1. If item is a value object or list object, an + invalid reverse property value + has been detected and processing is aborted.
                2. +
              2. Use add value to add item + to the property entry in reverse map + using true for as array.
                3. +
              +
              2. +
            +
            3. +
          +
          5. +
        5. Continue with the next key from element.
          6. +
        +
        14. +
      14. If expanded property is @nest, + add key to nests, initializing it to an empty array, + if necessary. + Continue with the next key from element.
        15. +
      15. When the frameExpansion flag is set, + if expanded property is any other + framing keyword (@default, + @embed, @explicit, @omitDefault, or + @requireAll), + set expanded value to the result of performing the + Expansion Algorithm + recursively, passing active context, + active property, value for element, + base URL, + and the frameExpansion + and ordered flags.
        16. +
      16. Unless expanded value is null, + expanded property is @value, + and input type is not @json, + set the expanded property entry of result to + expanded value.
        17. +
      17. Continue with the next key from element.
        18. +
      +
      5. +
    5. Initialize container mapping to key's container mapping in + active context.
      6. +
    6. If key's term definition in active context + has a type mapping of @json, + set expanded value to a new map, set the entry + @value to value, and set the entry @type to @json.
      7. +
    7. Otherwise, if container mapping includes @language and + value is a map then value + is expanded from a language map + as follows: +
        +
      1. Initialize expanded value to an empty + array.
        2. +
      2. Initialize direction to the default base direction from active context.
        3. +
      3. If key's term definition in active context + has a direction mapping, + update direction with that value.
        4. +
      4. For each key-value pair language-language value + in value, ordered lexicographically by language if ordered is true: +
          +
        1. If language value is not an array + set language value to an array containing only + language value.
          2. +
        2. For each item in language value: +
            +
          1. If item is null, + continue to the next entry in language value.
            2. +
          2. item must be a string, + otherwise an + invalid language map value + error has been detected and processing is aborted.
            3. +
          3. Initialize a new map v + consisting of two + key-value pairs: (@value-item) + and (@language-language). + If item is neither @none nor well-formed according to + section 2.2.9 of [BCP47], + processors SHOULD issue a warning. +
            Note
            Processors MAY normalize language tags to lower case.
            +
            4. +
          4. If language is @none, + or expands to @none, remove @language from v.
            5. +
          5. + If direction is not null, + add an entry for @direction to v with direction.
            6. +
          6. Append v to expanded value.
            7. +
          +
          3. +
        +
        5. +
      +
      8. +
    8. Otherwise, if container mapping + includes @index, + @type, or @id and + value is a map then value + is expanded from an map as follows: +
        +
      1. Initialize expanded value to an empty array.
        2. +
      2. Initialize index key to + the key's index mapping in active context, + or @index, if it does not exist.
        3. +
      3. For each key-value pair index-index value + in value, ordered lexicographically by index + if ordered is true: +
          +
        1. If container mapping includes @id or @type, + initialize map context to the previous context + from active context if it exists, + otherwise, set map context to active context.
          2. +
        2. If container mapping includes @type + and index's term definition in + map context has a local context, update + map context to the result of the + Context Processing algorithm, + passing map context as active context + the value of the index's local context + as local context + and base URL from the term definition for index + in map context.
          3. +
        3. Otherwise, set map context to active context.
          4. +
        4. Initialize expanded index to the result of + IRI expanding index.
          5. +
        5. If index value is not an array + set index value to an array containing only + index value.
          6. +
        6. Initialize index value to the result of + using this algorithm recursively, passing + map context as active context, + key as active property, + index value as element, + base URL, + true for from map, + and the frameExpansion + and ordered flags.
          7. +
        7. For each item in index value: +
            +
          1. If container mapping includes @graph, + and item is not a graph object, + set item to a new map containing the key-value pair + @graph-item, + ensuring that the value is represented using an array.
            2. +
          2. If container mapping includes @index, + index key is not @index, + and expanded index is not @none: +
              +
            1. Initialize re-expanded index to the result of calling + the Value Expansion algorithm, + passing the active context, + index key as active property, + and index as value.
              2. +
            2. Initialize expanded index key to the result of + IRI expanding index key.
              3. +
            3. Initialize index property values to + an array consisting of re-expanded index followed + by the existing values of + the concatenation of expanded index key in item, + if any.
              4. +
            4. Add the key-value pair (expanded index key-index property values) + to item.
              5. +
            5. If item is a value object, + it MUST NOT contain any extra properties; + an invalid value object + error has been detected and processing is aborted.
              6. +
            +
            3. +
          3. Otherwise, if container mapping includes @index, + item does not have an entry @index, + and expanded index is not @none, + add the key-value pair (@index-index) to item.
            4. +
          4. Otherwise, if container mapping includes @id + item does not have the entry @id, + and expanded index is not @none, + add the key-value pair (@id-expanded index) to item, + where expanded index is set to the result of + IRI expandingindex + using true for document relative + and false for vocab.
            5. +
          5. Otherwise, if container mapping includes @type + and expanded index is not @none, + initialize types to a new array + consisting of expanded index followed by any existing + values of @type in item. + Add the key-value pair (@type-types) to item.
            6. +
          6. Append item to expanded value.
            7. +
          +
          8. +
        +
        4. +
      +
      9. +
    9. Otherwise, initialize expanded value to the result of + using this algorithm recursively, passing active context, + key for active property, value for element, + base URL, + and the frameExpansion + and ordered flags.
      10. +
    10. If expanded value is null, ignore key + by continuing to the next key from element.
      11. +
    11. If container mapping includes @list and + expanded value is not already a list object, + convert expanded value to a list object + by first setting it to an array containing only + expanded value if it is not already an array, + and then by setting it to a map containing + the key-value pair @list-expanded value.
      12. +
    12. If container mapping includes + @graph, + and includes neither @id nor @index, + convert expanded value into an array, if necessary, + then convert each value ev in expanded value into a + graph object: +
        +
      1. Convert ev into + a graph object by creating a map containing the key-value + pair @graph-ev + where ev is represented as an array. +
        Note
        This may lead to a graph object including another graph object, + if ev was already in the form of a graph object.
        2. +
      +
      13. +
    13. If the term definition associated to + key indicates that it is a reverse property +
        +
      1. If result has no @reverse entry, create + one and initialize its value to an empty map.
        2. +
      2. Reference the value of the @reverse entry in result + using the variable reverse map.
        3. +
      3. If expanded value is not an array, set + it to an array containing expanded value.
        4. +
      4. For each item in expanded value +
          +
        1. If item is a value object or list object, an + invalid reverse property value + has been detected and processing is aborted.
          2. +
        2. If reverse map has no expanded property entry, + create one and initialize its value to an empty array.
          3. +
        3. Use add value to add item + to the expanded property entry in reverse map + using true for as array.
          4. +
        +
        5. +
      +
      14. +
    14. Otherwise, key is not a reverse property + use add value to add expanded value + to the expanded property entry in result + using true for as array. +
      15. +
    +
    14. +
  14. For each key nesting-key in nests, + ordered lexicographically if ordered is true: +
      +
    1. Initialize nested values to the value of nesting-key + in element, ensuring that it is an array.
      2. +
    2. For each nested value in nested values: +
        +
      1. If nested value is not a map, or any key within + nested value expands to @value, an + invalid @nest value error + has been detected and processing is aborted.
        2. +
      2. Recursively repeat steps 13 + and 14 + using nested value for element. +
        Note
        By invoking steps 13 + and 14 on nested value + we are able to unfold arbitrary levels of nesting, with results being merged into + result. + Step 13 iterates through each + entry in nested value and expands it, while collecting new + nested values found at each level, until all nesting has been extracted.
        +
        3. +
      +
      3. +
    +
    15. +
  15. If result contains the entry @value: +
      +
    1. The result must not contain any entries other than + @direction, + @index, + @language, + @type, + and @value. + It must not contain an @type entry if it contains either @language or @direction entries. + Otherwise, an invalid value object + error has been detected and processing is aborted.
      2. +
    2. If the result's @type entry + is @json, then the @value entry may + contain any value, and is treated as a JSON literal.
      3. +
    3. Otherwise, if the value of result's @value entry is + null, or an empty array, return null.
      4. +
    4. Otherwise, if the value of result's @value entry + is not a string and result contains the entry + @language, an + invalid language-tagged value + error has been detected (only strings + can be language-tagged) and processing is aborted.
      5. +
    5. Otherwise, if the result has an @type entry + and its value is not an IRI, an + invalid typed value + error has been detected and processing is aborted.
      6. +
    +
    16. +
  16. Otherwise, if result contains the entry @type + and its associated value is not an array, set it to + an array containing only the associated value.
    17. +
  17. Otherwise, if result contains the entry @set + or @list: +
      +
    1. The result must contain at most one other entry + which must be @index. Otherwise, an + invalid set or list object + error has been detected and processing is aborted.
      2. +
    2. If result contains the entry @set, then + set result to the entry's associated value.
      3. +
    +
    18. +
  18. If result is a map that contains only the entry + @language, return null.
    19. +
  19. If active property is null or @graph, + drop free-floating values as follows: +
      +
    1. If result is a map which is empty, + or contains only the entries @value or @list, + set result to null.
      2. +
    2. Otherwise, if result is a map whose only + entry is @id, set result to null. + + When the frameExpansion flag is set, a map + containing only the @id entry is retained.
      3. +
    +
    20. +
  20. Return result.
    21. +
+
+
+ +

5.2 IRI Expansion

+ +

In JSON-LD documents, some keys and values may represent + IRIs. This section defines an algorithm for + transforming a string that represents an IRI into + an absolute IRI or blank node identifier. + It also covers transforming keyword aliases + into keywords.

+ +

IRI expansion may occur during context processing or during + any of the other JSON-LD algorithms. If IRI expansion occurs during context + processing, then the local context and its related defined + map from the Context Processing algorithm + are passed to this algorithm. This allows for term definition + dependencies to be processed via the + Create Term Definition algorithm.

+ +
+

5.2.1 Overview

This section is non-normative.

+ +

In order to expand value to an IRI, we must + first determine if it is null, a term, a + keyword alias, or some form of IRI. Based on what + we find, we handle the specific kind of expansion; for example, we expand + a keyword alias to a keyword and a term + to an IRI according to its IRI mapping + in the active context. While inspecting value we + may also find that we need to create term definition + dependencies because we're running this algorithm during context processing. + We can tell whether or not we're running during context processing by + checking local context against null. + We know we need to create a term definition in the + active context when value is + an entry in the local context and the defined map + does not have an entry for value with an associated value of + true. The defined map is used during + Context Processing to keep track of + which terms have already been defined or are + in the process of being defined. We create a + term definition by using the + Create Term Definition algorithm.

+ +
Note

Values that have the form of a keyword, + but are not keywords (i.e., they begin with "@") do not + map to any value, as they are reserved for future use. + The algorithm returns null, so that they will be ignored when encountered.

+
+ +
+

5.2.2 Algorithm

+ +

The algorithm takes two required and four optional input variables. The + required inputs are an active context and a value + to be expanded. The optional inputs are two flags, + document relative and vocab, that specifying + whether value can be interpreted as a relative IRI reference + against the document's base IRI or the + active context's + vocabulary mapping, respectively, and + a local context and a map defined to be used when + this algorithm is used during Context Processing. + If not passed, the two flags are set to false and + local context and defined are initialized to null.

+ +
    +
  1. If value is a keyword or null, + return value as is.
    2. +
  2. + If value has the form of a keyword + (i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]), + a processor SHOULD generate a warning and return null.
    3. +
  3. If local context is not null, it contains + an entry with a key that equals value, and the value of the entry + for value in defined is not true, + invoke the Create Term Definition algorithm, + passing active context, local context, + value as term, and defined. This will ensure that + a term definition is created for value in + active context during Context Processing. +
    4. +
  4. If active context has a term definition for + value, and the associated IRI mapping is a keyword, + return that keyword.
    5. +
  5. If vocab is true and the + active context has a term definition for + value, return the associated IRI mapping.
    6. +
  6. If value contains a colon (:) + anywhere after the first character, + it is either + an IRI, a compact IRI, or a + blank node identifier: +
      +
    1. Split value into a prefix and suffix + at the first occurrence of a colon (:).
      2. +
    2. If prefix is underscore (_) + or suffix begins with double-forward-slash + (//), return value as it is already an + IRI or a blank node identifier.
      3. +
    3. If local context is not null, it + contains a prefix entry, and the value + of the prefix entry in defined + is not true, invoke the + Create Term Definition algorithm, + passing active context, + local context, prefix as term, + and defined. This will ensure that a + term definition is created for prefix + in active context during + Context Processing.
      4. +
    4. If active context contains a term definition + for prefix + having a non-null IRI mapping + and the prefix flag of the term definition is true, + return the result of concatenating the IRI mapping + associated with prefix and suffix.
      5. +
    5. If value has the form of an IRI, + return value.
      6. +
    +
    7. +
  7. If vocab is true, and + active context has a vocabulary mapping, + return the result of concatenating the vocabulary mapping + with value.
    8. +
  8. Otherwise, if document relative is true + set value to the result of resolving value against + the base IRI from active context. Only the basic algorithm in + section 5.2 + of [RFC3986] is used; neither + Syntax-Based Normalization nor + Scheme-Based Normalization + are performed. Characters additionally allowed in IRI references are treated + in the same way that unreserved characters are treated in URI references, per + section 6.5 + of [RFC3987].
    9. +
  9. Return value as is.
    10. +
+
+
+ +

5.3 Value Expansion

+ +

Some values in JSON-LD can be expressed in a + compact form. These values are required + to be expanded at times when processing + JSON-LD documents. A value is said to be in expanded form + after the application of this algorithm.

+ +
+

5.3.1 Overview

This section is non-normative.

+ +

If active property has a type mapping in the + active context set to @id or @vocab, + and the value is a string, + a map with a single entry @id whose + value is the result of using the + IRI Expansion algorithm on value + is returned.

+ +

Otherwise, the result will be a map containing + an @value entry whose value is the passed value. + Additionally, an @type entry will be included if there is a + type mapping associated with the active property + or an @language entry if value is a + string and there is language mapping associated + with the active property.

+ +

Note that values interpreted as IRIs fall into two categories: + those that are document relative, and those that are + vocabulary relative. Properties and values of @type, + along with terms marked as "@type": "@vocab" + are vocabulary relative, meaning that they need to be either + a defined term, a compact IRI + where the prefix is a term, + or a string which is turned into an IRI using + the vocabulary mapping.

+
+ +
+

5.3.2 Algorithm

+ +

The algorithm takes three required inputs: an active context, + an active property, and a value to expand.

+ +
    +
  1. If the active property has a type mapping + in active context that is @id, + and the value is a string, + return a new + map containing a single entry where the + key is @id and the value is the result + IRI expanding value + using true for document relative + and false for vocab.
    2. +
  2. If active property has a type mapping in + active context that is @vocab, + and the value is a string, + return a new + map containing a single entry where the + key is @id and the value is the result of + IRI expanding value + using true for document relative.
    3. +
  3. Otherwise, initialize result to a map + with an @value entry whose value is set to + value.
    4. +
  4. If active property has a type mapping in + active context, + other than @id, @vocab, or @none, + add @type to + result and set its value to the value associated with the + type mapping.
    5. +
  5. Otherwise, if value is a string: +
      +
    1. Initialize language to the language mapping for active property + in active context, if any, otherwise to the default language + of active context.
      2. +
    2. Initialize direction to the direction mapping for active property + in active context, if any, otherwise to the default base direction + of active context.
      3. +
    3. If language is not null, + add @language to result with the value language.
      4. +
    4. If direction is not null, + add @direction to result with the value direction.
      5. +
    +
    6. +
  6. Return result.
    7. +
+
+
+ +
+ + +

6. Compaction Algorithms

+ +

The following sections describe algorithms for compacting JSON-LD + documents, IRIs and values.

+ +

6.1 Compaction Algorithm

+ +

This algorithm compacts a JSON-LD document, such that the given + context is applied. This must result in shortening + any applicable IRIs to + terms or + compact IRIs, any applicable + keywords to + keyword aliases, and + any applicable JSON-LD values + expressed in expanded form to simple values such as + strings or + numbers.

+ +
+

6.1.1 Overview

This section is non-normative.

+ +

Starting with its root element, we can process the + JSON-LD document recursively, until we have a fully + compacted result. When + compacting an element, we can treat + each one differently according to its type, in order to break down the + problem:

+ +
    +
  1. If the element is a scalar, it is + already in compacted form, so we simply return it.
    2. +
  2. If the element is an array, we compact + each of its items recursively and return them in a new + array.
    3. +
  3. Otherwise element is a map. The value + of each entry in element is compacted recursively. Some of the entry keys will be + compacted, using the IRI Compaction algorithm, + to terms or compact IRIs + and others will be compacted from keywords to + keyword aliases or simply left + unchanged because they do not have definitions in the context. + Values will be converted to compacted form via the + Value Compaction algorithm. Some data + will be reshaped based on container mapping + specified in the context such as @index or @language + maps.
    4. +
+
+ +
+

6.1.2 Algorithm

+ +

The algorithm takes three required and two optional input variables. + The required inputs are an active context, + an active property, + and an element to be compacted. + The optional inputs are the + compactArrays flag + and the ordered flag, used to order + map entry keys lexicographically, where noted. + If not passed, both flags are set to false.

+ +
    +
  1. Initialize type-scoped context to active context. + This is used for compacting values that may be relevant to any previous + type-scoped context.
    2. +
  2. If element is a scalar, it is already in its most + compact form, so simply return element.
    3. +
  3. If element is an array: +
      +
    1. Initialize result to an empty array.
      2. +
    2. For each item in element: +
        +
      1. Initialize compacted item to the result of using this + algorithm recursively, passing active context, + active property, + item for element, + and the compactArrays + and ordered flags.
        2. +
      2. If compacted item is not null, then append + it to result.
        3. +
      +
      3. +
    3. If result is empty or contains more than one value, + or compactArrays is false, + or active property is either @graph or @set, + or container mapping for active property in + active context includes either @list or @set, + return result.
      4. +
    4. Otherwise, return the value in result.
      5. +
    +
    4. +
  4. Otherwise element is a map.
    5. +
  5. If active context has a previous context, + the active context is not propagated. + If element does not contain an @value entry, + and element does not consist of a single @id entry, + set active context to previous context from active context, + as the scope of a term-scoped context does not apply when processing new node objects.
    6. +
  6. If the term definition for active property in active context + has a local context: +
      +
    1. Set active context to the result of the + Context Processing algorithm, + passing active context, + the value of the active property's local context as local context, + + base URL from the term definition for active property + in active context, + and true for override protected.
      2. +
    +
    7. +
  7. If element has an @value or @id + entry and the result of using the + Value Compaction algorithm, + passing active context, + active property, and element as value is + a scalar, + or the term definition for active property + has a type mapping of @json, + return that result.
    8. +
  8. If element is a + list object, and the container mapping for + active property in active context includes @list, + return the result of using this algorithm recursively, passing + active context, + active property, value of @list + in element for element, + and the compactArrays + and ordered flags.
    9. +
  9. Initialize inside reverse to true if + active property equals @reverse, + otherwise to false.
    10. +
  10. Initialize result to an empty map.
    11. +
  11. If element has an @type entry, + create a new array compacted types initialized + by transforming each expanded type of that entry + into its compacted form + by IRI compacting expanded type. + Then, for each term + in compacted types ordered lexicographically: +
      +
    1. If the term definition for term in type-scoped context has a + local context + set active context to the result of the + Context Processing algorithm, + passing active context and the value of term's + local context in type-scoped context as local context + + base URL from the term definition for term + in type-scoped context, + and false for propagate. +
      2. +
    +
    12. +
  12. For each key expanded property and value expanded value + in element, ordered lexicographically by expanded property + if ordered is true: +
      +
    1. If expanded property is @id: +
        +
      1. If expanded value is a string, + then initialize compacted value + by IRI compacting expanded value + with vocab set to false.
        2. +
      2. Initialize alias + by IRI compacting expanded property.
        3. +
      3. Add an entry alias to result whose value is + set to compacted value and continue to the next + expanded property.
        4. +
      +
      2. +
    2. If expanded property is @type: +
        +
      1. If expanded value is a string, + then initialize compacted value + by IRI compacting expanded value + using type-scoped context for active context.
        2. +
      2. Otherwise, expanded value must be a + @type array: +
          +
        1. Initialize compacted value to an empty + array.
          2. +
        2. For each item expanded type in + expanded value: +
            +
          1. Set term + by IRI compacting expanded type + using type-scoped context for active context.
            2. +
          2. Append term, to compacted value.
            3. +
          +
          3. +
        +
        3. +
      3. Initialize alias + by IRI compacting expanded property.
        4. +
      4. Initialize as array + to true if processing mode is json-ld-1.1 and + the container mapping for alias in the + active context includes @set, + otherwise to the negation of compactArrays.
        5. +
      5. Use add value to add compacted value + to the alias entry in result + using as array.
        6. +
      6. Continue to the next expanded property.
        7. +
      +
      3. +
    3. If expanded property is @reverse: +
        +
      1. Initialize compacted value to the result of using this + algorithm recursively, passing active context, + @reverse for + active property, expanded value + for element, + and the compactArrays + and ordered flags.
        2. +
      2. For each property and value in compacted value: +
          +
        1. If the term definition for property in the + active context indicates that property is + a reverse property +
            +
          1. Initialize as array + to true if the container mapping for property in the + active context includes @set, + otherwise the negation of compactArrays.
            2. +
          2. Use add value to add value + to the property entry in result + using as array.
            3. +
          3. Remove the property entry from + compacted value.
            4. +
          +
          2. +
        +
        3. +
      3. If compacted value has some remaining map entries, i.e., + it is not an empty map: +
          +
        1. Initialize alias + by IRI compacting @reverse.
          2. +
        2. Set the value of the alias entry of result to + compacted value.
          3. +
        +
        4. +
      4. Continue with the next expanded property from element.
        5. +
      +
      4. +
    4. If expanded property is @preserve + then: +
        +
      1. Initialize compacted value to the result of using this + algorithm recursively, passing + active context, + active property, + expanded value for element, + and the compactArrays + and ordered flags.
        2. +
      2. Add compacted value as the value of @preserve + in result unless expanded value is an empty array.
        3. +
      +
      5. +
    5. If expanded property is @index and + active property has a container mapping + in active context that includes @index, + then the compacted result will be inside of an @index + container, drop the @index entry by continuing + to the next expanded property.
      6. +
    6. Otherwise, if expanded property is + @direction, + @index, + @language, + or @value: +
        +
      1. Initialize alias + by IRI compacting expanded property.
        2. +
      2. Add an entry alias to result whose value is + set to expanded value and continue with the next + expanded property.
        3. +
      +
      7. +
    7. If expanded value is an empty array: +
        +
      1. Initialize item active property + by IRI compacting expanded property + using expanded value for value + and inside reverse for reverse.
        2. +
      2. If the term definition for item active property + in the active context has a nest value + entry (nest term): +
          +
        1. If nest term is not @nest, + or a term in the active context that expands to @nest, + an invalid @nest value + error has been detected, and processing is aborted.
          2. +
        2. If result does not have a nest term entry, + initialize it to an empty map.
          3. +
        3. Initialize nest result to the value of nest term in result.
          4. +
        +
        3. +
      3. Otherwise, initialize nest result to result.
        4. +
      4. Use add value to add an empty array + to the item active property entry in nest result + using true for as array.
        5. +
      +
      8. +
    8. + At this point, expanded value must be an + array due to the + Expansion algorithm. + For each item expanded item in expanded value: +
        +
      1. Initialize item active property + by IRI compacting expanded property + using expanded item for value + and inside reverse for reverse.
        2. +
      2. If the term definition for item active property + in the active context has a nest value + entry (nest term): +
          +
        1. If nest term is not @nest, + or a term in the active context that expands to @nest, + an invalid @nest value + error has been detected, and processing is aborted.
          2. +
        2. If result does not have a nest term entry, + initialize it to an empty map.
          3. +
        3. Initialize nest result to the value of nest term in result.
          4. +
        +
        3. +
      3. Otherwise, initialize nest result to result.
        4. +
      4. Initialize container to container mapping for + item active property in active context, + or to a new empty array, if there is no such container mapping.
        5. +
      5. Initialize as array + to true if container includes @set, + or if item active property is @graph or @list, + otherwise the negation of compactArrays.
        6. +
      6. Initialize compacted item to the result of using + this algorithm recursively, passing + active context, + item active property for active property, + expanded item for element, + along with the compactArrays + and ordered flags. + If expanded item is a list object or a graph object, + use the value of the @list or @graph entries, + respectively, for element instead of expanded item.
        7. +
      7. If expanded item is a list object: +
          +
        1. If compacted item is not an array, + then set compacted item to an array containing only + compacted item.
          2. +
        2. If container does not include @list: +
            +
          1. Convert compacted item to a + list object by setting it to a + map containing an entry + where the key is the result of + IRI compacting @list + and the value is the original compacted item.
            2. +
          2. If expanded item contains the entry + @index-value, then add an entry + to compacted item where the key is the + result of + IRI compacting @index + and value is value.
            3. +
          3. Use add value to add compacted item + to the item active property entry in + nest result + using as array.
            4. +
          +
          3. +
        3. Otherwise, set the value of the item active property entry + in nest result to compacted item.
          4. +
        +
        8. +
      8. If expanded item is a graph object: +
          +
        1. If container includes @graph and @id: +
            +
          1. Initialize map object to the value of item active property + in nest result, + initializing it to a new empty map, if necessary.
            2. +
          2. Initialize map key + by IRI compacting + the value of @id in expanded item + or @none if no such value exists + with vocab set to false + if there is an @id entry in expanded item.
            3. +
          3. Use add value to add compacted item + to the map key entry in map object + using as array.
            4. +
          +
          2. +
        2. Otherwise, if container includes @graph and @index + and expanded item is a simple graph object: +
            +
          1. Initialize map object to the value of item active property + in nest result, + initializing it to a new empty map, if necessary.
            2. +
          2. Initialize map key the value of @index in + expanded item or @none, if no such + value exists.
            3. +
          3. Use add value to add compacted item + to the map key entry in map object + using as array.
            4. +
          +
          3. +
        3. Otherwise, if container includes @graph + and expanded item is a simple graph object + the value cannot be represented as a map object. +
            +
          1. If compacted item is an array + with more than one value, it cannot be directly represented, + as multiple objects would be interpreted as different named graphs. + Set compacted item to a new map, + containing the key + from IRI compacting @included + and the original compacted item as the value.
            2. +
          2. Use add value to add compacted item + to the item active property entry in nest result + using as array.
            3. +
          +
          4. +
        4. Otherwise, container does not include @graph + or otherwise does not match one of the previous cases. +
            +
          1. Set compacted item to a new map containing + the key + from IRI compacting @graph + using the original compacted item as a value.
            2. +
          2. If expanded item contains an @id entry, + add an entry in compacted item using the key + from IRI compacting @id + using the value + of IRI compacting the value of @id in expanded item + using false for vocab.
            3. +
          3. If expanded item contains an @index entry, + add an entry in compacted item using the key + from IRI compacting @index + and the value of @index in expanded item.
            4. +
          4. Use add value to add compacted item + to the item active property entry in nest result + using as array.
            5. +
          +
          5. +
        +
        9. +
      9. + Otherwise, if container includes @language, + @index, @id, + or @type + and container does not include @graph: +
          +
        1. Initialize map object to the value of item active property + in nest result, + initializing it to a new empty map, if necessary.
          2. +
        2. Initialize container key + by IRI compacting + either @language, @index, @id, or @type + based on the contents of container.
          3. +
        3. Initialize index key to the value of index mapping in + the term definition associated with item active property in active context, + or @index, if no such value exists.
          4. +
        4. If container includes @language and + expanded item contains a + @value entry, then set compacted item + to the value associated with its @value entry. + Set map key to the value of @language in expanded item, if any.
          5. +
        5. Otherwise, if container includes @index + and index key is @index, + set map key to the value of @index in expanded item, if any.
          6. +
        6. Otherwise, if container includes @index + and index key is not @index: +
            +
          1. Reinitialize container key by IRI compacting + index key.
            2. +
          2. Set map key to the first value of container key in compacted item, if any.
            3. +
          3. If there are remaining values in compacted item + for container key, use add value to + add those remaining values to the container key in compacted item. + Otherwise, remove that entry from compacted item.
            4. +
          +
          7. +
        7. Otherwise, if container includes @id, set + map key to the value of container key in + compacted item and remove container key from compacted item.
          8. +
        8. Otherwise, if container includes @type: +
            +
          1. Set map key to the first value of container key in compacted item, if any.
            2. +
          2. If there are remaining values in compacted item + for container key, use add value to + add those remaining values to the container key in compacted item.
            3. +
          3. Otherwise, remove that entry from compacted item.
            4. +
          4. If compacted item contains a single entry with a key expanding + to @id, set compacted item + to the result of using + this algorithm recursively, passing + active context, + item active property for active property, + and a map composed of the single entry for @id from expanded item for element. + +
            5. +
          +
          9. +
        9. If map key is null, + set it to the result of + IRI compacting @none.
          10. +
        10. Use add value to add compacted item + to the map key entry in map object + using as array.
          11. +
        +
        10. +
      10. Otherwise, use add value to add compacted item + to the item active property entry in nest result + using as array.
        11. +
      +
      9. +
    +
    13. +
  13. Return result.
    14. +
+
+
+ +

6.2 IRI Compaction

+ +

This algorithm compacts an IRI to a term or + compact IRI, or a keyword to a + keyword alias. A value that is associated with the + IRI may be passed in order to assist in selecting the most + context-appropriate term.

+ +
+

6.2.1 Overview

This section is non-normative.

+ +

If the passed IRI is null, + we simply return null. + Otherwise, we first try to find a term that the IRI or keyword + can be compacted to if it is relative to + active context's vocabulary mapping. + In order to select the most appropriate term, + we may have to collect information about the passed value. + This information includes determining the preferred container mapping, + type mapping or language mapping + for expressing the value. + For JSON-LD lists, the type mapping + or language mapping will be chosen based on the most + specific values that work for all items in the list. + Once this information is gathered, + it is passed to the Term Selection algorithm, + which will return the most appropriate term.

+ +

If no term was found that could be used to compact the IRI, + an attempt is made to compact the IRI + using the active context's vocabulary mapping, + if there is one. + If the IRI could not be compacted, + an attempt is made to find a compact IRI. + A term will be used to create a compact IRI + only if the term definition contains the prefix flag + with the value true. + If there is no appropriate compact IRI, + and the compactToRelative option is true, + the IRI is transformed to a relative IRI reference + using the document's base IRI. + Finally, if the IRI or keyword still could not be compacted, + it is returned as is.

+ +

When considering language mapping, + the direction mapping is also considered, either with, or without, + a language mapping, + and the language mapping is normalized to lower case.

+ +

In the case were this algorithm would return the input IRI as is, + and that IRI can be mistaken for a compact IRI in the active context, + this algorithm will raise an error, + because it has no way to return an unambiguous representation of the original IRI.

+
+ +
+

6.2.2 Algorithm

+ +

This algorithm takes two required inputs and three optional inputs. + The required inputs are an active context, + and the var to be compacted. + The optional inputs are a value associated with the var, + a vocab flag which specifies whether the passed var + should be compacted using the active context's vocabulary mapping, + and a reverse flag which specifies whether a reverse property is being compacted. + If not passed, value is set to null + and both vocab and reverse are both set to false.

+ +
    +
  1. If var is null, return null.
    2. +
  2. If the active context has a null + inverse context, + set inverse context in active context + to the result of calling the + Inverse Context Creation algorithm + using active context.
    3. +
  3. Initialize inverse context to the value of + inverse context in active context.
    4. +
  4. If vocab is true and var is an + entry of inverse context: +
      +
    1. Initialize default language + based on the active context's + default language, normalized to lower case and default base direction: +
        +
      1. If the active context's default base direction + is not null, to the concatenation of + the active context's default language + and default base direction, separated by an underscore ("_"), + normalized to lower case.
        2. +
      2. Otherwise, to the active context's default language, + if it has one, + normalized to lower case, + otherwise to @none.
        3. +
      +
      2. +
    2. If value is a map containing an @preserve entry, + use the first element from the value of @preserve as value.
      3. +
    3. Initialize containers to an empty array. This + array will be used to keep track of an ordered list of + preferred container mapping for a term, + based on what is compatible with value. +
      Note
      + Algorithm steps may append the same value to containers, + but the order in which they are added is significant for choosing the most appropriate term. +
      +
      4. +
    4. Initialize type/language to @language, + and type/language value to @null. These two + variables will keep track of the preferred + type mapping or language mapping for + a term, based on what is compatible with value.
      5. +
    5. If value is a map containing an @index entry, + and value is not a graph object + then append the values @index and @index@set to containers.
      6. +
    6. If reverse is true, set type/language + to @type, type/language value to + @reverse, and append @set to containers.
      7. +
    7. Otherwise, if value is a list object, then set + type/language and type/language value + to the most specific values that work for all items in + the list as follows: +
        +
      1. If @index is not an entry in value, then + append @list to containers.
        2. +
      2. Initialize list to the array associated + with the @list entry in value.
        3. +
      3. Initialize common type and common language to null. If + list is empty, set common language to + default language.
        4. +
      4. For each item in list: +
          +
        1. Initialize item language to @none and + item type to @none.
          2. +
        2. If item contains an @value entry: +
            +
          1. If item contains an @direction entry, + then set item language to the concatenation of + the item's @language entry (if any) + the item's @direction, separated by an underscore ("_"), + normalized to lower case.
            2. +
          2. Otherwise, if item contains an @language entry, + then set item language to its associated value, + normalized to lower case.
            3. +
          3. Otherwise, if item contains a + @type entry, set item type to its + associated value.
            4. +
          4. Otherwise, set item language to + @null.
            5. +
          +
          3. +
        3. Otherwise, set item type to @id.
          4. +
        4. If common language is null, + set common language to item language.
          5. +
        5. Otherwise, if item language does not equal + common language and item contains a + @value entry, then set common language + to @none because list items have conflicting + languages.
          6. +
        6. If common type is null, + set common type to item type.
          7. +
        7. Otherwise, if item type does not equal + common type, then set common type + to @none because list items have conflicting + types.
          8. +
        8. If common language is @none and + common type is @none, then + stop processing items in the list because it has been + detected that there is no common language or type amongst + the items.
          9. +
        +
        5. +
      5. If common language is null, + set common language to @none.
        6. +
      6. If common type is null, + set common type to @none.
        7. +
      7. If common type is not @none then set + type/language to @type and + type/language value to common type.
        8. +
      8. Otherwise, set type/language value to + common language.
        9. +
      +
      8. +
    8. Otherwise, if value is a graph object, + prefer a mapping most appropriate for the particular value. +
        +
      1. If value contains an @index entry, + append the values @graph@index and @graph@index@set + to containers.
        2. +
      2. If value contains an @id entry, + append the values @graph@id and @graph@id@set + to containers.
        3. +
      3. Append the values @graph @graph@set, + and @set + to containers.
        4. +
      4. If value does not contain an @index entry, + append the values @graph@index and @graph@index@set + to containers.
        5. +
      5. If the value does not contain an @id entry, + append the values @graph@id and @graph@id@set + to containers.
        6. +
      6. Append the values @index and @index@set + to containers.
        7. +
      7. Set type/language to @type + and set type/language value to @id.
        8. +
      +
      9. +
    9. Otherwise: +
        +
      1. If value is a value object: +
          +
        1. If value contains an @direction entry + and does not contain an @index entry, + then set type/language value to the concatenation of + the value's @language entry (if any) + and the value's @direction entry, separated by an underscore ("_"), + normalized to lower case. + Append @language and @language@set to containers.
          2. +
        2. Otherwise, if value contains an @language entry + and does not contain an @index entry, + then set type/language value to + the value of @language normalized to lower case, + and append @language, + and @language@set to + containers.
          3. +
        3. Otherwise, if value contains an + @type entry, then set type/language value to + its associated value and set type/language to + @type.
          4. +
        +
        2. +
      2. Otherwise, set type/language to @type + and set type/language value to @id, + and append @id, @id@set, + @type, and @set@type, + to containers.
        3. +
      3. Append @set to containers.
        4. +
      +
      10. +
    10. Append @none to containers. This represents + the non-existence of a container mapping, and it will + be the last container mapping value to be checked as it + is the most generic.
      11. +
    11. + If processing mode is not json-ld-1.0 and value is not a map + or does not contain an @index entry, + append @index and @index@set to containers. +
    12. + If processing mode is not json-ld-1.0 and + value is a map containing only an @value entry, + append @language and @language@set to containers.
      13. +
    13. If type/language value is null, + set type/language value to @null. + This is the key under which null values + are stored in the inverse context entry.
      14. +
    14. Initialize preferred values to an empty array. + This array will indicate, in order, the preferred values for + a term's type mapping or + language mapping.
      15. +
    15. If type/language value is @reverse, append + @reverse to preferred values.
      16. +
    16. If type/language value is @id or @reverse and + value is a map containing an @id entry: +
        +
      1. If the result of + IRI compacting + the value of the @id entry in value + has a term definition in the active context + with an IRI mapping that equals the value of the @id entry in value, + then append @vocab, @id, and + @none, in that order, to preferred values.
        2. +
      2. Otherwise, append @id, @vocab, and + @none, in that order, to preferred values.
        3. +
      +
      17. +
    17. Otherwise, append type/language value and @none, in + that order, to preferred values. + If value is a list object + with an empty array as the value of @list, + set type/language to @any.
      18. +
    18. Append @any to preferred values.
      19. +
    19. If preferred values + contains any entry having an underscore ("_"), + append the substring of that entry from the underscore to the end of the string + to preferred values.
      20. +
    20. Initialize term to the result of the + Term Selection algorithm, passing + var, containers, + type/language, and preferred values.
      21. +
    21. If term is not null, return term.
      22. +
    +
    5. +
  5. At this point, there is no simple term that var + can be compacted to. If vocab is true and + active context has a vocabulary mapping: +
      +
    1. If var begins with the + vocabulary mapping's value + but is longer, then initialize suffix to the substring + of var that does not match. If suffix does not + have a term definition in active context, + then return suffix.
      2. +
    +
    6. +
  6. The var could not be compacted using the + active context's vocabulary mapping. + Try to create a compact IRI, starting by initializing + compact IRI to null. This variable will be used to + store the created compact IRI, if any.
    7. +
  7. For each term definition definition in active context: +
      +
    1. If the IRI mapping of definition is null, + its IRI mapping equals var, + its IRI mapping is not a substring at the beginning of + var, + or definition does not have + a true prefix flag, + definition's key cannot be used as a prefix. + Continue with the next definition.
      2. +
    2. Initialize candidate by concatenating definition key, + a colon (:), and the substring of var + that follows after the value of the + definition's IRI mapping.
      3. +
    3. If either compact IRI is null, candidate is + shorter or the same length but lexicographically less than + compact IRI and candidate does not have a + term definition in active context, or if that + term definition has an IRI mapping + that equals var and value is null, + set compact IRI to candidate.
      4. +
    +
    8. +
  8. If compact IRI is not null, return compact IRI.
    9. +
  9. To ensure that the IRI var is + not confused with a compact IRI, + if the IRI scheme of var + matches any term in active context with prefix flag set to true, + and var has no IRI authority (preceded by double-forward-slash (//), + an IRI confused with prefix error has been detected, + and processing is aborted.
    10. +
  10. If vocab is false, + transform var to a relative IRI reference using + the base IRI from active context, if it exists.
    11. +
  11. Finally, return var as is.
    12. +
+
+
+ +

6.3 Value Compaction

+ +

Expansion transforms all values into expanded form + in JSON-LD. This algorithm performs the opposite operation, transforming + a value into compacted form. This algorithm compacts a + value according to the term definition in the given + active context that is associated with the value's associated + active property.

+ +
+

6.3.1 Overview

This section is non-normative.

+ +

The value to compact has either an @id or an + @value entry.

+ +

For the former case, if the type mapping of + active property is set to @id or @vocab + and value consists of only an @id entry and, if + the container mapping of active property + includes @index, an @index entry, value + can be compacted to a string by returning the result of + using the IRI Compaction algorithm + to compact the value associated with the @id entry. + Otherwise, value cannot be compacted and is returned as is.

+ +

For the latter case, it might be possible to compact value + just into the value associated with the @value entry. + This can be done if the active property has a matching + type mapping or language mapping and there + is either no @index entry or the container mapping + of active property includes @index. It can + also be done if @value is the only entry in value + (apart an @index entry in case the container mapping + of active property includes @index) and + either its associated value is not a string, there is + no default language, or there is an explicit + null language mapping for the + active property.

+
+ +
+

6.3.2 Algorithm

+ +

This algorithm has three required inputs: an active context, + an active property, and a value + to be compacted.

+ +
    +
  1. Initialize result to a copy of value.
    2. +
  2. If the active context has a null + inverse context, + set inverse context in active context + to the result of calling the + Inverse Context Creation algorithm + using active context.
    3. +
  3. Initialize inverse context to the value of + inverse context in active context.
    4. +
  4. Initialize language to the language mapping for active property + in active context, if any, otherwise to the default language + of active context.
    5. +
  5. Initialize direction to the direction mapping for active property + in active context, if any, otherwise to the default base direction + of active context.
    6. +
  6. If value has an @id entry + and has no other entries other than @index: +
      +
    1. If the type mapping of active property + is set to @id, set result to the result of + IRI compacting + the value associated with the @id entry + using false for vocab.
      2. +
    2. Otherwise, if the type mapping of active property + is set to @vocab, set result to the result of + IRI compacting + the value associated with the @id entry.
      3. +
    +
    7. +
  7. Otherwise, if value has an @type entry whose + value matches the type mapping of active property, + set result to the value associated with the @value entry + of value.
    8. +
  8. Otherwise, if the type mapping of active property is @none, + or value has an @type entry, + and the value of @type in value does not match the type mapping of active property, + leave value as is, as value compaction is disabled. +
      +
    1. Replace any value of @type in result with the result of + IRI compacting + the value of the @type entry.
      2. +
    +
    9. +
  9. Otherwise, if the value of the @value entry is not a string: +
      +
    1. If value has an @index entry, + and the container mapping associated to active property + includes @index, + or if value has no @index entry, + set result to the value associated with the @value entry.
      2. +
    +
    10. +
  10. Otherwise, if value has an @language entry + whose value exactly matches language, + using a case-insensitive comparison + if it is not null, or is not present, if language is null, + and the value has an @direction entry + whose value exactly matches direction, + if it is not null, or is not present, if direction is null: +
      +
    1. If value has an @index entry, + and the container mapping associated to active property + includes @index, + or value has no @index entry, + set result to the value associated with the @value entry.
      2. +
    +
    11. +
  11. If result is a map, + replace each key in result with the result of + IRI compacting that key.
    12. +
  12. Return result.
    13. +
+
+
+
+ +

7. Flattening Algorithms

+ +

The following sections describe algorithms for flattening JSON-LD documents, + creating node maps, and generating blank nodes.

+ +

7.1 Flattening Algorithm

+ +

This algorithm flattens an expanded JSON-LD document by collecting all + properties of a node in a single map + and labeling all blank nodes with + blank node identifiers. + This resulting uniform shape of the document, may drastically simplify + the code required to process JSON-LD data in certain applications.

+ +
+

7.1.1 Overview

This section is non-normative.

+ +

First, a node map is generated using the + Node Map Generation algorithm + which collects all properties of a node in a single + map. In the next step, the node map is + converted to a JSON-LD document in + flattened document form.

+
+ +
+

7.1.2 Algorithm

+ +

The algorithm takes one required and one optional input variables. + The required input is an element to flatten. + The optional input is + the ordered flag, used to order + map entry keys lexicographically, where noted. + If not passed, the ordered flag is set to false.

+ +

This algorithm uses the + Generate Blank Node Identifier algorithm + to generate new blank node identifiers + and relabel existing blank node identifiers. + The Generate Blank Node Identifier algorithm + maintains an identifier map + to ensure that blank node identifiers in the source + document are consistently remapped to new blank node identifiers + avoiding collisions. + Thus, before this algorithm is run, the identifier map is reset.

+ +
    +
  1. Initialize node map to a map consisting of + a single entry whose key is @default and whose value is + an empty map.
    2. +
  2. Perform the Node Map Generation algorithm, passing + element and node map.
    3. +
  3. Initialize default graph to the value of the @default + entry of node map, which is a map representing + the default graph.
    4. +
  4. For each key-value pair graph name-graph in node map + where graph name is not @default, + ordered lexicographically by graph name + if ordered is true, + perform the following steps: +
      +
    1. If default graph does not have a graph name entry, create + one and initialize its value to a map consisting of an + @id entry whose value is set to graph name.
      2. +
    2. Reference the value associated with the graph name entry in + default graph using the variable entry.
      3. +
    3. Add an @graph entry to entry and set it to an + empty array.
      4. +
    4. For each id-node pair in graph ordered lexicographically by id + if ordered is true, + add node to the @graph entry of entry, + unless the only entry of node is @id.
      5. +
    +
    5. +
  5. Initialize an empty array flattened.
    6. +
  6. For each id-node pair in default graph ordered lexicographically by id + if ordered is true, + add node to flattened, + unless the only entry of node is @id.
    7. +
  7. Return flattened.
    8. +
+
+
+ +

7.2 Node Map Generation

+ +

This algorithm creates a map node map holding an indexed + representation of the graphs and nodes + represented in the passed expanded document. All nodes that are not + uniquely identified by an IRI get assigned a (new) blank node identifier. + The resulting node map will have an map entry for every graph in the document whose + value is another object with an entry for every node represented in the document. + The default graph is stored under the @default entry, all other graphs are + stored under their graph name.

+ +
+

7.2.1 Overview

This section is non-normative.

+ +

The algorithm recursively runs over an expanded JSON-LD document to + collect all entries of a node + in a single map. The algorithm updates a + map node map whose keys represent the + graph names used in the document + (the default graph is stored under the @default entry) + and whose associated values are maps + which index the nodes in the + graph. If a + entry's value is a node object, + it is replaced by a node object consisting of only an + @id entry. If a node object has no @id + entry or it is identified by a blank node identifier, + a new blank node identifier is generated. This relabeling + of blank node identifiers is + also done for properties and values of + @type.

+
+ +
+

7.2.2 Algorithm

+ +

The algorithm takes as input an expanded JSON-LD document element and a reference to + a map node map. Furthermore it has the optional parameters + active graph (which defaults to @default), an active subject, + active property, and a reference to a map list. If + not passed, active subject, active property, and list are + set to null.

+ +
    +
  1. If element is an array, process each item in element + as follows and then return: +
      +
    1. Run this algorithm recursively by passing item for element, + node map, active graph, active subject, + active property, and list.
      2. +
    +
    2. +
  2. Otherwise element is a map. Reference the + map which is the value of the active graph + entry of node map using the variable graph. If the + active subject is null, set node to null + otherwise reference the active subject entry of graph using the + variable subject node.
    3. +
  3. For each item in the @type entry of element, + if any, or for the value of @type, if the value of @type exists and is not an array: +
      +
    1. If item is a blank node identifier, replace it with a newly + generated blank node identifier + passing item for identifier.
      2. +
    +
    4. +
  4. If element has an @value entry, perform the following steps: +
      +
    1. If list is null: +
        +
      1. If subject node does not have an active property entry, + create one and initialize its value to an array + containing element.
        2. +
      2. Otherwise, compare element against every item in the + array associated with the active property + entry of subject node. If there is no item equivalent to element, + append element to the array. Two + maps are considered + equal if they have equivalent map entries.
        3. +
      +
      2. +
    2. Otherwise, append element to the @list entry of list.
      3. +
    +
    5. +
  5. Otherwise, if element has an @list entry, perform + the following steps: +
      +
    1. Initialize a new map result consisting of a single entry + @list whose value is initialized to an empty array.
      2. +
    2. Recursively call this algorithm passing the value of element's + @list entry for element, node map, active graph, + active subject, active property, and + result for list.
      3. +
    3. If list is null, + append result to the value of the active property entry + of subject node.
      4. +
    4. Otherwise, append result to the @list entry of list.
      5. +
    +
    6. +
  6. Otherwise element is a node object, perform + the following steps: +
      +
    1. If element has an @id entry, set id + to its value and remove the entry from element. If id + is a blank node identifier, replace it with a newly + generated blank node identifier + passing id for identifier.
      2. +
    2. Otherwise, set id to the result of the + Generate Blank Node Identifier algorithm + passing null for identifier.
      3. +
    3. If graph does not contain an entry id, create one and initialize + its value to a map consisting of a single entry @id whose + value is id.
      4. +
    4. Reference the value of the id entry of graph using the + variable node.
      5. +
    5. If active subject is a map, a reverse property relationship + is being processed. Perform the following steps: +
        +
      1. If node does not have a active property entry, + create one and initialize its value to an array + containing active subject.
        2. +
      2. Otherwise, compare active subject against every item in the + array associated with the active property + entry of node. If there is no item equivalent to active subject, + append active subject to the array. Two + maps are considered + equal if they have equivalent map entries.
        3. +
      +
      6. +
    6. Otherwise, if active property is not null, perform the following steps: +
        +
      1. Create a new map reference consisting of a single entry + @id whose value is id.
        2. +
      2. If list is null: +
          +
        1. If subject node does not have an active property entry, + create one and initialize its value to an array + containing reference.
          2. +
        2. Otherwise, compare reference against every item in the + array associated with the active property + entry of subject node. If there is no item equivalent to reference, + append reference to the array. Two + maps are considered + equal if they have equivalent map entries.
          3. +
        +
        3. +
      3. Otherwise, append reference to the @list entry of list.
        4. +
      +
      7. +
    7. If element has an @type entry, append + each item of its associated array to the + array associated with the @type entry of + node unless it is already in that array. Finally + remove the @type entry from element.
      8. +
    8. If element has an @index entry, set the @index + entry of node to its value. If node already has an + @index entry with a different value, a + conflicting indexes + error has been detected and processing is aborted. Otherwise, continue by + removing the @index entry from element.
      9. +
    9. If element has an @reverse entry: +
        +
      1. Create a map referenced node with a single entry @id whose + value is id.
        2. +
      2. Initialize reverse map to the value of the @reverse entry of + element.
        3. +
      3. For each key-value pair property-values in reverse map: +
          +
        1. For each value of values: +
            +
          1. Recursively invoke this algorithm passing value for + element, node map, active graph, + referenced node for active subject, and + property for active property. Passing a + map for active subject indicates to the + algorithm that a reverse property relationship is being processed.
            2. +
          +
          2. +
        +
        4. +
      4. Remove the @reverse entry from element.
        5. +
      +
      10. +
    10. If element has an @graph entry, recursively invoke this + algorithm passing the value of the @graph entry for element, + node map, and id for active graph before removing + the @graph entry from element.
      11. +
    11. If element has an @included entry, + recursively invoke this algorithm passing the value of the @included entry for element, + node map, and active graph + before removing the @included entry from element.
      12. +
    12. Finally, for each key-value pair property-value in element ordered by + property perform the following steps: +
        +
      1. If property is a blank node identifier, replace it with a newly + generated blank node identifier + passing property for identifier. +
        Note
        The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD.
        2. +
      2. If node does not have a property entry, create one and initialize + its value to an empty array.
        3. +
      3. Recursively invoke this algorithm passing value for element, + node map, active graph, id for active subject, + and property for active property.
        4. +
      +
      13. +
    +
    7. +
+
+
+ +

7.3 Merge Node Maps

+

This algorithm creates a new map of subjects to nodes using all graphs + contained in the graph map created using the Node Map Generation algorithm + to create merged node objects containing information defined for a given subject + in each graph contained in the node map.

+ +
    +
  1. Create result as an empty map
    2. +
  2. For each graph name and node map in graph map + and for each id and node in node map: +
      +
    1. Initialize merged node to the value for id in result, initializing it + with a new map consisting of a single entry @id whose value is id, if it does not exist.
      2. +
    2. For each property and values in node: +
        +
      1. If property is a keyword other than @type, add property and values to merged node.
        2. +
      2. Otherwise, merge each element from values into the values for property + in merged node, initializing it to an empty array if necessary.
        3. +
      +
      3. +
    +
    3. +
  3. Return result.
    4. +
+
+ +

7.4 Generate Blank Node Identifier

+ +

This algorithm is used to generate new + blank node identifiers or to + relabel an existing blank node identifier to avoid collision + by the introduction of new ones.

+ +
+

7.4.1 Overview

This section is non-normative.

+ +

The simplest case is if there exists already a blank node identifier + in the identifier map for the passed identifier, in which + case it is simply returned. Otherwise, a new blank node identifier + is generated. If the passed identifier is not null, + an entry is created in the identifier map associating the + identifier with the blank node identifier.

+
+ +
+

7.4.2 Algorithm

+ +

The algorithm takes a single input variable identifier which may + be null. The algorithm + maintains an identifier map to relabel existing + blank node identifiers to new blank node identifiers, + which is reset when the invoking algorithm is initialized.

+ +
    +
  1. If identifier is not null and has an entry in the + identifier map, return the mapped identifier.
    2. +
  2. Otherwise, generate a new unique blank node identifier.
    3. +
  3. If identifier is not null, create a new entry + for identifier in identifier map and set its value + to the new blank node identifier.
    4. +
  4. Return the new blank node identifier.
    5. +
+ +
Note

+ One way of generating new blank node identifiers is to maintain a counter + and increment it when generating a new identifier and appending it to + a string such as _:b. +

+
+
+ +
+ +

8. RDF Serialization/Deserialization Algorithms

+ +

This section describes algorithms to deserialize a JSON-LD document to an + RDF dataset and vice versa. The algorithms are designed for in-memory + implementations with random access to map elements.

+ +

8.1 Deserialize JSON-LD to RDF Algorithm

+ +

This algorithm deserializes a JSON-LD document to an RDF dataset. + Please note that RDF does not allow a blank node to be used + as a property, while JSON-LD does. Therefore, by default + triples that would have contained blank nodes as properties are + discarded when interpreting JSON-LD as RDF.

+ +
Note

The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD.

+ +

If the rdfDirection option is not null, then special processing is used to + convert from an i18n-datatype or compound-literal form.

+ +

Implementations MUST generate only well-formed + triples and graph names:

+ + +
+

8.1.1 Overview

This section is non-normative.

+ +

The JSON-LD document is expanded and converted to a node map using the + Node Map Generation algorithm. + This allows each graph represented within the document to be + extracted and flattened, making it easier to process each + node object. + Each graph from the node map is processed to extract triple, + to which any (non-default) graph name is applied to create an RDF dataset. + Each node object in the node map has an @id entry + which corresponds to the subject, + the other entries represent predicates. + Each entry value is either an IRI or blank node identifier + or can be transformed to anRDF literal + to generate an triple. + Lists are transformed into an RDF collection + using the List to RDF Conversion algorithm.

+
+ +
+

8.1.2 Algorithm

+ +

The algorithm takes a map node map, which + is the result of the Node Map Generation algorithm and + an RDF dataset dataset into which new graphs and triples are added. + It also takes two optional input variables produceGeneralizedRdf + and rdfDirection. + Unless the produceGeneralizedRdf option + is set to true, triple + containing a blank node predicate + are excluded from output.

+ +
Note

The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, + as is the support for generalized RDF Datasets + and thus the produceGeneralizedRdf option may be also be removed.

+ +
    +
  1. For each graph name and graph in node map + ordered by graph name: +
      +
    1. If graph name is + not well-formed, continue + with the next graph name-graph pair.
      2. +
    2. If graph name is @default, + initialize triples to the value of the defaultGraph + attribute of dataset. + Otherwise, initialize triples as an empty RdfGraph + and add to dataset using its + add method along with graph name + for graphName.
      3. +
    3. For each subject and node in graph ordered + by subject: +
        +
      1. If subject is + not well-formed, continue + with the next subject-node pair.
        2. +
      2. For each property and values in node + ordered by property: +
          +
        1. If property is @type, then for each + type in values, + create a new RdfTriple + composed of subject, rdf:type for predicate, + and type for object + and add to triples + using its add method, + unless type is not well-formed.
          2. +
        2. Otherwise, if property is a keyword + continue with the next property-values pair.
          3. +
        3. Otherwise, if property is a blank node identifier and + the produceGeneralizedRdf option is not true, + continue with the next property-values pair. +
          Note
          The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, + as is the support for generalized RDF Datasets + and thus the produceGeneralizedRdf option may be also be removed.
          +
          4. +
        4. Otherwise, if property is + not well-formed, + continue with the next property-values pair.
          5. +
        5. Otherwise, property is an IRI or + blank node identifier. For each item + in values: +
            +
          1. Initialize list triples as an empty array. +
            Note
            + item is a value object, list object, + or a node object.
            +
            2. +
          2. Add a triple + composed of subject, property, and + the result of using the + Object to RDF Conversion algorithm + passing item + and list triples + to triples using its add method, + unless the result is null, + indicating a non-well-formed resource + that has to be ignored.
            3. +
          3. Add all RdfTriple instances from + list triples to triples using + its add method.
            4. +
          +
          6. +
        +
        3. +
      +
      4. +
    +
    2. +
+
+
+ +

8.2 Object to RDF Conversion

+ +

This algorithm takes a node object, list object, or value object + and transforms it into an resource to be used as the object of an triple. + If a node object containing a relative IRI reference is passed to + the algorithm, null is returned which then causes the resulting + triple to be ignored. + If the input is a list object, it will also + return the triples created from that input.

+ +
+

8.2.1 Overview

This section is non-normative.

+ +

Value objects are transformed to + RDF literals as described in + § 8.6 Data Round Tripping + whereas node objects are transformed + to IRIs, + blank node identifiers, + or null.

+
+ +
+

8.2.2 Algorithm

+ +

The algorithm takes as two arguments item which MUST be + either a value object, list object, or node object + and list triples, which is an empty array.

+ +
    +
  1. If item is a node object and the value of + its @id entry is + not well-formed, return + null.
    2. +
  2. If item is a node object, return the + IRI or blank node identifier associated + with its @id entry.
    3. +
  3. If item is a list object + return the result of the + List Conversion algorithm, passing + the value associated with the @list entry from + item and list triples. +
    4. +
  4. Otherwise, item is a value object. Initialize + value to the value associated with the @value + entry in item. +
  5. Initialize datatype to the value associated with the + @type entry of item or null if + item does not have such an entry.
    6. +
  6. If datatype is not null + and neither a well-formed IRI nor @json, + return null.
    7. +
  7. If item has an @language + entry which is not well-formed, return null.
    8. +
  8. If datatype is @json, + convert value to the canonical lexical form + using the result of transforming the internal representation of value + to JSON and set datatype to rdf:JSON. +
    Issue
    The JSON Canonicalization Scheme (JCS) [RFC8785] + is an emerging standard for JSON canonicalization. + This specification will likely be updated to require such a canonical representation. + Users are cautioned from depending on the + JSON literal lexical representation as an RDF literal, + as the specifics of serialization may change in a future revision of this document.
    9. +
  9. If value is true or + false, set value to the string + true or false which is the + canonical lexical form as described in + § 8.6 Data Round Tripping + If datatype is null, + set datatype to xsd:boolean.
    10. +
  10. Otherwise, if value is a number with a non-zero fractional + part (the result of a modulo‑1 operation) + or an absolute value greater or equal to 1021, + or value is a number + and datatype equals xsd:double, convert value to a + string in canonical lexical form of + an xsd:double as defined in [XMLSCHEMA11-2] + and described in + § 8.6 Data Round Tripping. + If datatype is null, + set datatype to xsd:double.
    11. +
  11. Otherwise, if value is a number, + convert it to a string in canonical lexical form of + an xsd:integer as defined in [XMLSCHEMA11-2] + and described in + § 8.6 Data Round Tripping. + If datatype is null, + set datatype to xsd:integer. +
    Note
    It follows from the previous step that value + has no non-zero fractional part.
    12. +
  12. Otherwise, if datatype is null, + set datatype to xsd:string or rdf:langString, + depending on if item has an @language entry.
    13. +
  13. If item contains an @direction entry + and rdfDirection is not null, + item is a value object which is serialized using special rules. +
      +
    1. + Initialize language to the value of @language in item + normalized to lower case, + or the empty string ("") if there is no such entry. +
      Note
      Generally, language tags are not normalized, + but when creating an i18n-datatype or compound-literal + values are normalized to lower case for improved interoperability.
      +
      2. +
    2. If rdfDirection is i18n-datatype, + set datatype to the result of appending language + and the value of @direction in item separated by an underscore ("_") + to https://www.w3.org/ns/i18n#. + Initialize literal as an RDF literal using + value and datatype. +
      Note
      Processors MAY normalize language tags to lower case.
      +
      Note
      As @direction may be used without @language, + it is possible, and legitimate, to create a datatype IRI + such as http://w3.org/ns/i18n#_ltr, which does not encode a language tag.
      3. +
    3. Otherwise, if rdfDirection is compound-literal: +
        +
      1. Initialize literal as a new blank node.
        2. +
      2. Create a new triple using literal as the subject, + rdf:value as the predicate, and the value of @value in item + as the object, and add it to list triples.
        3. +
      3. If the item has an entry for @language, + create a new triple using literal as the subject, + rdf:language as the predicate, and language + as the object, and add it to list triples.
        4. +
      4. Create a new triple using literal as the subject, + rdf:direction as the predicate, and the value of @direction in item + as the object, and add it to list triples.
        5. +
      +
      4. +
    +
    14. +
  14. Otherwise, initialize literal as an RDF literal using + value and datatype. If item has an + @language entry, add the value associated with the + @language entry as the language tag of literal.
    15. +
  15. Return literal.
    16. +
+
+
+ +

8.3 List to RDF Conversion

+ +

List Conversion is the process of taking a list object + and transforming it into an + RDF collection + as defined in RDF Semantics [RDF11-MT].

+ +
+

8.3.1 Overview

This section is non-normative.

+ +

For each element of the list a new blank node identifier + is allocated which is used to generate rdf:first and + rdf:rest. The + algorithm returns the list head, which is either the first allocated + blank node identifier or rdf:nil if the + list is empty. If a list element represents an IRI, + the corresponding rdf:first triple is omitted.

+
+ +
+

8.3.2 Algorithm

+ +

The algorithm takes two inputs: an array list + and an empty array list triples used for returning + the generated triples.

+ +
    +
  1. If list is empty, return rdf:nil.
    2. +
  2. Otherwise, create an array bnodes composed of a + newly generated blank node identifier + for each entry in list.
    3. +
  3. For each pair of subject from bnodes and item from list: +
      +
    1. Initialize embedded triples to a new empty array.
      2. +
    2. Initialize object to the result of using the + Object to RDF Conversion algorithm + passing item + and embedded triples for list triples.
      3. +
    3. Unless object is null, append a triple + composed of subject, rdf:first, and object + to list triples.
      4. +
    4. Initialize rest as the next entry in bnodes, or if that + does not exist, rdf:nil. Append a + triple composed of subject, + rdf:rest, and rest to list triples.
      5. +
    5. Append all values from embedded triples to list triples
      6. +
    +
    4. +
  4. Return the first blank node from bnodes or + rdf:nil if bnodes is empty.
    5. +
+
+
+ +

8.4 Serialize RDF as JSON-LD Algorithm

+ +

This algorithm serializes an RDF dataset consisting of a + default graph and zero or more + named graphs into a JSON-LD document.

+ +

In the RDF abstract syntax, RDF literals have a + lexical form, as defined + in [RDF11-CONCEPTS]. The form of these literals is used when creating JSON-LD values based on these literals.

+ +
+

8.4.1 Overview

This section is non-normative.

+ +

Iterate through each graph in the dataset, converting each + RDF collection into a list + and generating a JSON-LD document in expanded form for all + RDF literals, IRIs + and blank node identifiers. + If the useNativeTypes flag is set to true, + RDF literals with a + datatype IRI + that equals xsd:integer or xsd:double are converted + to a JSON numbers and RDF literals + with a datatype IRI + that equals xsd:boolean are converted to true or + false based on their + lexical form + as described in + § 8.6 Data Round Tripping. + Unless the useRdfType flag is set to true, rdf:type + predicates will be serialized as @type as long as the associated object is + either an IRI or blank node identifier.

+ +

If the rdfDirection option is not null, then special processing is used to + convert from an i18n-datatype or compound-literal form.

+
+ +
+

8.4.2 Algorithm

+ +

The algorithm takes one required and four optional inputs: + an RDF dataset dataset + and the four optional arguments are + the ordered flag, defaulting to false, used to order + map entry keys lexicographically, where noted, + rdfDirection defaulting to null, + the useNativeTypes flag, defaulting to false, + and the useRdfType flag, defaulting to false.

+ +

The dataset is iterable to iterate over graphs and graph names + contained within the RdfDataset. Each graph is also iterable + for iterating over triples contained within the RdfGraph.

+ +
    +
  1. Initialize default graph to an empty map.
    2. +
  2. Initialize graph map to a map consisting + of a single entry @default whose value references + default graph.
    3. +
  3. Initialize referenced once to an empty map.
    4. +
  4. Initialize compound literal subjects to an empty map.
    5. +
  5. For each graph in dataset: +
      +
    1. If graph is the default graph, + initialize name to @default, otherwise to the + graph name associated with graph.
      2. +
    2. If graph map has no name entry, create one and set + its value to an empty map.
      3. +
    3. If compound literal subjects has no name entry, create one and set + its value to an empty map.
      4. +
    4. If graph is not the default graph and + default graph does not have a name entry, + create such an entry and initialize its value to a new + map with a single entry @id + whose value is name.
      5. +
    5. Reference the value of the name entry in graph map + using the variable node map.
      6. +
    6. Reference the value of the name entry in compound literal subjects + using the variable compound map.
      7. +
    7. For each triple in graph + consisting of subject, predicate, and object: +
        +
      1. If node map does not have a subject entry, + create one and initialize its value to a new map + consisting of a single entry @id whose value is + set to subject.
        2. +
      2. Reference the value of the subject entry in node map + using the variable node.
        3. +
      3. If the rdfDirection option + is compound-literal and predicate is rdf:direction, + add an entry in compound map for subject with the value true.
        4. +
      4. If object is an IRI or blank node identifier, + and node map does not have an object entry, + create one and initialize its value to a new map + consisting of a single entry @id whose value is + set to object.
        5. +
      5. If predicate equals rdf:type, the + useRdfType flag is not true, and object + is an IRI or blank node identifier, + append object to the value of the @type + entry of node; unless such an item already exists. + If no such entry exists, create one + and initialize it to an array whose only item is + object. Finally, continue to the next + triple.
        6. +
      6. Initialize value to the result of using the + RDF to Object Conversion algorithm, + passing object, + rdfDirection, + and useNativeTypes.
        7. +
      7. If node does not have a predicate entry, create one + and initialize its value to an empty array.
        8. +
      8. If there is no item equivalent to value in the array + associated with the predicate entry of node, append a + reference to value to the array. Two maps + are considered equal if they have equivalent map entries.
        9. +
      9. If object is rdf:nil, it represents + the termination of an RDF collection: +
          +
        1. Reference the usages entry of the object + entry of node map using the variable usages.
          2. +
        2. Append a new map consisting of three + entries, node, property, and value + to the usages array. The node entry + is set to a reference to node, property to predicate, + and value to a reference to value.
          3. +
        +
        10. +
      10. Otherwise, if referenced once has an entry for object, + set the object entry of referenced once to false.
        11. +
      11. Otherwise, if object is a blank node identifier, + it might represent a list node: +
          +
        1. Set the object entry of referenced once to a new map consisting of three + entries, node, property, and value + to the usages array. The node entry + is set to a reference to node, property to predicate, + and value to a reference to value.
          2. +
        +
        12. +
      +
      8. +
    +
    6. +
  6. For each name and graph object in graph map: +
      +
    1. If compound literal subjects + has an entry for name, then for each cl + which is a key in that entry: +
        +
      1. Initialize cl entry to the value of cl + in referenced once, + continuing to the next cl if cl entry is not a map.
        2. +
      2. Initialize node to the value of node in cl entry.
        3. +
      3. Initialize property to value of property in cl entry.
        4. +
      4. Initialize value to value of value in cl entry.
        5. +
      5. Initialize cl node to the value of cl + in graph object, and remove that entry from graph object, + continuing to the next cl if cl node is not a map.
        6. +
      6. For each cl reference in the value of property in node + where the value of @id in cl reference is cl: +
          +
        1. Delete the @id entry in cl reference.
          2. +
        2. Add an entry to cl reference for @value with the value taken + from the rdf:value entry in cl node.
          3. +
        3. Add an entry to cl reference for @language with the value taken + from the rdf:language entry in cl node, if any. + If that value is not well-formed according to + section 2.2.9 of [BCP47], + an invalid language-tagged string + error has been detected and processing is aborted.
          4. +
        4. Add an entry to cl reference for @direction with the value taken + from the rdf:direction entry in cl node, if any. + If that value is not "ltr" or "rtl", an + invalid base direction + error has been detected and processing is aborted.
          5. +
        +
        7. +
      +
      2. +
    2. If graph object has no rdf:nil entry, continue + with the next name-graph object pair as the graph does + not contain any lists that need to be converted.
      3. +
    3. Initialize nil to the value of the rdf:nil entry + of graph object.
      4. +
    4. For each item usage in the usages entry of + nil, perform the following steps: +
        +
      1. Initialize node to the value of the value of the + node entry of usage, property to + the value of the property entry of usage, + and head to the value of the value entry + of usage.
        2. +
      2. Initialize two empty arrays list + and list nodes.
        3. +
      3. While property equals rdf:rest, + the value of the @id entry + of node is a blank node identifier, + the value of the entry of referenced once associated with the @id + entry of node is a map, + node has rdf:first and rdf:rest entries, + both of which have as value an array consisting of a single element, + and node has no other entries apart from an optional @type + entry whose value is an array with a single item equal to + rdf:List, + node represents a well-formed list node. + Perform the following steps to traverse the list backwards towards its head: +
          +
        1. Append the only item of rdf:first entry of + node to the list array.
          2. +
        2. Append the value of the @id entry of + node to the list nodes array.
          3. +
        3. Initialize node usage to the value of the entry of referenced once associated with the @id + entry of node.
          4. +
        4. Set node to the value of the node entry + of node usage, property to the value of the + property entry of node usage, and + head to the value of the value entry + of node usage.
          5. +
        5. If the @id entry of node is an + IRI instead of a blank node identifier, + exit the while loop.
          6. +
        +
        4. +
      4. Remove the @id entry from head.
        5. +
      5. Reverse the order of the list array.
        6. +
      6. Add an @list entry to head and initialize + its value to the list array.
        7. +
      7. For each item node id in list nodes, remove the + node id entry from graph object.
        8. +
      +
      5. +
    +
    7. +
  7. Initialize an empty array result.
    8. +
  8. For each subject and node in default graph + ordered lexicographically by subject + if ordered is true: +
      +
    1. If graph map has a subject entry: +
        +
      1. Add an @graph entry to node and initialize + its value to an empty array.
        2. +
      2. For each key-value pair s-n in the subject + entry of graph map ordered lexicographically by s + if ordered is true, + append n to the @graph entry of node after + removing its usages entry, unless the only + remaining entry of n is @id.
        3. +
      +
      2. +
    2. Append node to result after removing its + usages entry, unless the only remaining entry of + node is @id.
      3. +
    +
    9. +
  9. Return result.
    10. +
+
+
+ +

8.5 RDF to Object Conversion

+ +

This algorithm transforms an RDF literal to a JSON-LD value object + and a RDF blank node or IRI to an JSON-LD node object.

+ +
+

8.5.1 Overview

This section is non-normative.

+ +

RDF literals are transformed to + value objects whereas IRIs and + blank node identifiers are + transformed to node objects.

+

Literals with datatype rdf:JSON + are transformed into a value object using the internal representation + based on the lexical-to-value mapping defined in + JSON datatype in [JSON-LD11], + and @type of @json.

+

With the rdfDirection option set to i18n-datatype, + literals with datatype starting with https://www.w3.org/ns/i18n# + are transformed into a value object by decoding + the language tag and base direction from the datatype.

+

With the rdfDirection option set to compound-literal, + blank node objects using rdf:direction are + are transformed into a value object by decoding + the rdf:value, rdf:language, and rdf:direction properties.

+

If the useNativeTypes flag is set to true, + RDF literals with a + datatype IRI + that equals xsd:integer or xsd:double are converted + to a JSON numbers and RDF literals + with a datatype IRI + that equals xsd:boolean are converted to true or + false based on their + lexical form + as described in + § 8.6 Data Round Tripping.

+
+ +
+

8.5.2 Algorithm

+ +

This algorithm takes three required inputs: + a value to be converted to a map, + rdfDirection, + and a flag useNativeTypes.

+ +
    +
  1. If value is an IRI or a + blank node identifier, return a new map + consisting of a single entry @id whose value is set to + value.
    2. +
  2. Otherwise value is an + RDF literal: +
      +
    1. Initialize a new empty map result.
      2. +
    2. Initialize converted value to value.
      3. +
    3. Initialize type to null
      4. +
    4. If useNativeTypes is true +
        +
      1. If the + datatype IRI + of value equals xsd:string, set + converted value to the + lexical form + of value.
        2. +
      2. Otherwise, if the + datatype IRI + of value equals xsd:boolean, set + converted value to true if the + lexical form + of value matches true, or false + if it matches false. If it matches neither, + set type to xsd:boolean.
        3. +
      3. Otherwise, if the + datatype IRI + of value equals xsd:integer or + xsd:double and its + lexical form + is a valid xsd:integer or xsd:double + according [XMLSCHEMA11-2], set converted value + to the result of converting the + lexical form + to a JSON number.
        4. +
      +
      5. +
    5. Otherwise, if processing mode is not json-ld-1.0, + and value is a JSON literal, + set converted value to the result of + turning the lexical value of value + into the JSON-LD internal representation, and set type to @json. + If the lexical value of value is not valid JSON according to + the JSON Grammar [RFC8259], + an invalid JSON literal + error has been detected and processing is aborted.
      6. +
    6. Otherwise, if the datatype IRI of value starts with https://www.w3.org/ns/i18n#, + and rdfDirection is i18n-datatype: +
        +
      1. Set converted value to the lexical form of value.
        2. +
      2. If the string prefix of the fragment identifier + of the datatype IRI up until the underscore ("_") is not empty, + add an entry @language to result and set its value to that prefix. +
        Note
        As @direction may be used without @language, + it is possible, and legitimate, to create a datatype IRI + such as http://w3.org/ns/i18n#_ltr, which does not encode a language tag.
        3. +
      3. Add an entry @direction to result and set its value to the substring of the + fragment identifier following + the underscore ("_").
        4. +
      +
      7. +
    7. Otherwise, if value is a + language-tagged string + add an entry @language to result and set its value to the + language tag of value.
      8. +
    8. Otherwise, set type to the + datatype IRI + of value, unless it equals xsd:string which is ignored.
      9. +
    9. Add an entry @value to result whose value + is set to converted value.
      10. +
    10. If type is not null, add an entry @type + to result whose value is set to type.
      11. +
    11. Return result.
      12. +
    +
    3. +
+
+
+ +

8.6 Data Round Tripping

+ +

When deserializing JSON-LD to RDF + JSON-native numbers are automatically + type-coerced to xsd:integer or xsd:double + depending on whether the number has a non-zero fractional part + or not (the result of a modulo‑1 operation), the boolean values + true and false are coerced to xsd:boolean, + and strings are coerced to xsd:string. + The JSON, numeric, or boolean values themselves are converted to + canonical lexical form, i.e., a deterministic string + representation as defined in [XMLSCHEMA11-2].

+ +

The canonical lexical form of an integer, i.e., a + number with no non-zero fractional part + and an absolute value less than 1021, + or a number coerced to xsd:integer, + is a finite-length sequence of decimal + digits (0-9) with an optional leading minus sign; leading + zeros are prohibited. In JavaScript, implementers can use the following + snippet of code to convert an integer to + canonical lexical form:

+ +
+
+ Example 20: Sample integer serialization implementation in JavaScript + 
(value).toFixed(0).toString()
+
+ +

The canonical lexical form of a double, i.e., a + number + with a non-zero fractional part or an absolute value greater or equal to 1021, + or a number + coerced to xsd:double, consists of a mantissa followed by the + character E, followed by an exponent. The mantissa is a + decimal number and the exponent is an integer. Leading zeros and a + preceding plus sign (+) are prohibited in the exponent. + If the exponent is zero, it is indicated by E0. For the + mantissa, the preceding optional plus sign is prohibited and the + decimal point is required. Leading and trailing zeros are prohibited + subject to the following: number representations must be normalized + such that there is a single digit which is non-zero to the left of + the decimal point and at least a single digit to the right of the + decimal point unless the value being represented is zero. The + canonical representation for zero is 0.0E0. + xsd:double's value space is defined by the IEEE + double-precision 64-bit floating point type [IEEE-754-2008] whereas + the value space of JSON numbers is not + specified; when deserializing JSON-LD to RDF the mantissa is rounded to + 15 digits after the decimal point. In JavaScript, implementers + can use the following snippet of code to convert a double to + canonical lexical form:

+ +
+
+ Example 21: Sample floating point number serialization implementation in JavaScript + 
(value).toExponential(15).replace(/(\d)0*e\+?/,'$1E')
+
+ +

The canonical lexical form of the boolean + values true and false are the strings + true and false.

+ +

The canonical lexical form of a JSON literal + is the result of serializing the internal representation + into the JSON format [RFC8259] in compliance with the constraints of the value space description within + The rdf:JSON Datatype of [JSON-LD11].

+ + + +

When JSON-native numbers are deserialized + to RDF, lossless data round-tripping cannot be guaranteed, as rounding + errors might occur. When + serializing RDF as JSON-LD, + similar rounding errors might occur. Furthermore, the datatype or the lexical + representation might be lost. An xsd:double with a value + of 2.0 will, e.g., result in an xsd:integer + with a value of 2 in canonical lexical form + when converted from RDF to JSON-LD and back to RDF. It is important + to highlight that in practice it might be impossible to losslessly + convert an xsd:integer to a number because + its value space is not limited. While the JSON specification [RFC8259] + does not limit the value space of numbers + either, concrete implementations typically do have a limited value + space.

+ +

To ensure lossless round-tripping the + Serialize RDF as JSON-LD Algorithm + specifies a useNativeTypes flag which controls whether + RDF literals + with a datatype IRI + equal to xsd:integer, xsd:double, or + xsd:boolean are converted to their JSON-native + counterparts. If the useNativeTypes flag is set to + false, all literals remain in their original string + representation.

+ +

Some JSON serializers, such as PHP's native implementation in some versions, + backslash-escape the forward slash character. For example, the value + http://example.com/ would be serialized as http:\/\/example.com\/. + This is problematic as other JSON parsers might not understand those escaping characters. + There is no need to backslash-escape forward slashes in JSON-LD. To aid + interoperability between JSON-LD processors, forward slashes MUST NOT be + backslash-escaped.

+
+
+ +

9. 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.

+ +

The JSON-LD API uses Promises to represent + the result of the various deferred operations. + Promises are defined in [ECMASCRIPT]. + General use within specifications can be found in [promises-guide]. + Implementations MAY chose to implement in an appropriate way for their native environments + as long as they generally use the same methods, arguments, and options + and return the same results.

+ +
Note

Interfaces are marked [Exposed=JsonLd], + which creates a global interface. + The use of WebIDL in JSON-LD, while appropriate for use within browsers, + is not limited to such use.

+ +

9.1 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 implementations do not modify the input parameters. + If an error is detected, the Promise is + rejected with a JsonLdError having an appropriate code + and processing is stopped.

+ +

If the documentLoader + 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.

+ + 
WebIDL/*
+ * The JsonLd interface is created to expose the JsonLdProcessor interface.
+ */
+[Global=JsonLd, Exposed=JsonLd]
+interface JsonLd {};
+
+[Exposed=JsonLd]
+interface JsonLdProcessor {
+  constructor();
+  static Promise<JsonLdRecord> compact(
+    JsonLdInput input,
+    optional JsonLdContext context = null,
+    optional JsonLdOptions options = {});
+  static Promise<sequence<JsonLdRecord>> expand(
+    JsonLdInput input,
+    optional JsonLdOptions options = {});
+  static Promise<JsonLdRecord> flatten(
+    JsonLdInput input,
+    optional JsonLdContext context = null,
+    optional JsonLdOptions options = {});
+  static Promise<sequence<JsonLdRecord>> fromRdf(
+    RdfDataset input,
+    optional JsonLdOptions options = {});
+  static Promise<RdfDataset> toRdf(
+    JsonLdInput input,
+    optional JsonLdOptions options = {});
+};
+ +
compact()
+
+

Compacts the given input using the + context according to the steps in the Compaction algorithm:

+ +

The final output is a map + derived from compacted output. + If compacted output is an array, it is + included with an entry of (a possibly aliased) @graph + with the value of compacted output, + otherwise compacted output is used as the map result. + If context not null, + an @context entry is added to the map result.

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. If the provided input + is a RemoteDocument, + initialize remote document to input.
    3. +
  3. Otherwise, if the provided input + is a string representing the IRI of a remote document, await and dereference it as remote document + using LoadDocumentCallback, passing input + for url, + and the extractAllScripts option from options + for extractAllScripts.
    4. +
  4. Set expanded input to the result of + using the expand() method + using either remote document + or input + if there is no remote document + for input, + and options, + with ordered set to false, + and extractAllScripts defaulting to false.
    5. +
  5. Set context base to the documentUrl + from remote document, if available, otherwise to the base option + from options.
    6. +
  6. If context is a map + having an @context entry, + set context to that entry's value, + otherwise to context.
    7. +
  7. Initialize active context + to the result of the Context Processing algorithm + passing a new empty context as active context + context as local context, + and context base as base URL.
    8. +
  8. Set base IRI in active context to the base option from options, if set; + otherwise, if the compactToRelative option is true, + to the IRI of the currently being processed document, if available; + otherwise to null.
    9. +
  9. Set compacted output to the result of using the Compaction algorithm, + using active context, + null for active property, + expanded input as element, + and the compactArrays + and ordered + flags from options. +
      +
    1. If compacted output is an empty array, + replace it with a new map.
      2. +
    2. Otherwise, if compacted output is an array, + replace it with a new map with a single entry + whose key is the result of + IRI compacting @graph + and value is compacted output.
      3. +
    3. If context was not null, + add an @context entry to compacted output and set its value + to the provided context.
      4. +
    +
    10. +
  10. Resolve the promise with compacted output + transforming compacted output from the + internal representation to a JSON serialization.
    11. +
+ +
+
input
+
The map, + array of maps to perform the compaction upon, + or an IRI referencing the JSON-LD document to compact.
+
context
+
The context to use when compacting the input; + it can be specified by using a map, + an IRI, + or an array consisting of maps and IRIs.
+
options
+
A set of options to configure the algorithms. + This allows, e.g., to set the input document's base IRI. + The JsonLdOptions type defines default option values. +
+
+
+ +
expand()
+
+

Expands the given input + according to the steps in the Expansion algorithm:

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. If the provided input + is a RemoteDocument, + initialize remote document to input.
    3. +
  3. Otherwise, if the provided input + is a string representing the IRI of a remote document, await and dereference it as remote document + using LoadDocumentCallback, passing input + for url, + the extractAllScripts option from options + for extractAllScripts.
    4. +
  4. If document + from remote document is a string, transform into the internal representation. + If document cannot be transformed to the internal representation, + reject promise passing a loading document failed error.
    5. +
  5. Initialize a new empty active context. + The base IRI and original base URL of the active context is set to the documentUrl + from remote document, if available; + otherwise to the base option from options. + If set, the base option from options overrides the base IRI.
    6. +
  6. If the expandContext option in options is set, + update the active context using the Context Processing algorithm, + passing the expandContext as local context + and the original base URL from active context as base URL. + If expandContext is a map having an @context entry, + pass that entry's value instead for local context.
    7. +
  7. If remote document has a contextUrl, + update the active context using the Context Processing algorithm, + passing the contextUrl as local context, + and contextUrl as base URL.
    8. +
  8. Set expanded output to the result of using the Expansion algorithm, + passing the active context, + document from remote document or input + if there is no remote document as element, + null as active property, + documentUrl as base URL, if available, + otherwise to the base option + from options, + and the frameExpansion + and and ordered + flags from options. +
    Note
    If there is no remote document, + then input is + a JsonLdRecord or a sequence of + JsonLdRecords, which are implicitly already in the + internal representation.
    +
      +
    1. If expanded output is a + map that contains only an @graph entry, + set expanded output that value.
      2. +
    2. If expanded output is null, + set expanded output to an empty array.
      3. +
    3. If expanded output is not an array, + set expanded output to an array containing only expanded output.
      4. +
    +
    9. +
  9. Resolve the promise with expanded output + transforming expanded output from the + internal representation to a JSON serialization.
    10. +
+ +
+
input
+
The map, + or array of maps to perform the expansion upon, + or an IRI referencing the JSON-LD document to expand.
+
options
+
A set of options to configure the used algorithms. + This allows, e.g., to set the input document's base IRI. + The JsonLdOptions type defines default option values. +
+
+
+ +
flatten()
+
+

Flattens the given input + and optionally compacts it using the provided context + according to the steps in the Flattening algorithm:

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. If the provided input + is a RemoteDocument, + initialize remote document to input.
    3. +
  3. Otherwise, if the provided input + is a string representing the IRI of a remote document, await and dereference it as remote document + using LoadDocumentCallback, passing input + for url, + and the extractAllScripts option from options + for extractAllScripts. +
    4. +
  4. Set expanded input to the result of + using the expand() method + using either remote document + or input + if there is no remote document + for input, + and options + with ordered set to false.
    5. +
  5. Initialize an empty identifier map.
    6. +
  6. Set flattened output to the result of using the Flattening algorithm, + passing expanded input as element, + and the ordered flag + from options. +
      +
    1. If context is not null, + set flattened output to the result of + using the compact() method + using flattened output for input, + context, + and options. + Set the base IRI in active context to the base option + from options, if set; + otherwise, if the compactToRelative option is true, + to the IRI of the currently being processed document, if available; + otherwise to null.
      2. +
    +
    7. +
  7. Resolve the promise with flattened output + transforming flattened output from the + internal representation to a JSON serialization, + if necessary.
    8. +
+ +
+
input
+
The map, + or array of maps, + or an IRI referencing the JSON-LD document to flatten.
+
context
+
The context to use when compacting the flattened expanded input; + it can be specified by using a map, + an IRI, or an array consisting of maps + and IRIs. + If null, the result will not be compacted but kept in expanded form.
+
options
+
A set of options to configure the used algorithms. + This allows, e.g., to set the input document's base IRI. + The JsonLdOptions type defines default option values. +
+
+
+ +
fromRdf()
+
+

Transforms the given input + into a JSON-LD document in expanded form + according to the steps in the Serialize RDF as JSON-LD Algorithm:

+ +
Note

This interface does not define a means of creating an RdfDataset + from an arbitrary input, other than the toRdf() method.

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. Set expanded result to the result of invoking the + Serialize RDF as JSON-LD Algorithm method + using dataset + and options.
    3. +
  3. Resolve the promise with expanded result + transforming expanded result from the + internal representation to a JSON serialization.
    4. +
+ +
+
input
+
The map, + or array of maps, + or an IRI referencing the JSON-LD document to flatten.
+
options
+
A set of options to configure the used algorithms. + This allows, e.g., to set the input document's base IRI. + The JsonLdOptions type defines default option values. +
+
+
+ +
toRdf()
+
+

Transforms the given input into an RdfDataset + according to the steps in the Deserialize JSON-LD to RDF Algorithm:

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. Set expanded input to the result of using the + expand() method + using input + and options + with ordered set to false.
    3. +
  3. Create a new RdfDataset dataset.
    4. +
  4. Create a new map node map.
    5. +
  5. Invoke the Node Map Generation algorithm, + passing expanded input as element + and node map.
    6. +
  6. Invoke the Deserialize JSON-LD to RDF Algorithm + passing node map, dataset, + and the produceGeneralizedRdf flag from options. +
    Note
    The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, + as is the support for generalized RDF Datasets + and thus the produceGeneralizedRdf option may be also be removed.
    +
    7. +
  7. Resolve the promise with dataset.
    8. +
+ +
+
input
+
The map, + or array of maps, + or an IRI referencing the JSON-LD document to flatten.
+
options
+
A set of options to configure the used algorithms. + This allows, e.g., to set the input document's base IRI. + The JsonLdOptions type defines default option values. +
+
+
+ + 
WebIDLtypedef record<USVString, any> JsonLdRecord;
+

The JsonLdRecord is the definition of a map + used to contain arbitrary map entries + which are the result of parsing a JSON Object. + + 

WebIDLtypedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;
+ +

The JsonLdInput interface is used to refer to an input value + that that may be a JsonLdRecord, + a sequence of JsonLdRecords, + a string representing an IRI, + which can be dereferenced to retrieve a valid JSON document, + or an already dereferenced RemoteDocument.

+ +

When the value is a JsonLdRecord or sequence of JsonLdRecords, + the values are taken as their equivalent internal representation values, + where a JsonLdRecord is equivalent to a map, + and a sequence of JsonLdRecords is equivalent to an array + of maps. The map entries are converted to their equivalents + in [INFRA].

+ + 
WebIDLtypedef (JsonLdRecord or sequence<(JsonLdRecord or USVString)> or USVString) JsonLdContext;
+ +

The JsonLdContext interface is used to refer to a value + that may be a JsonLdRecord, + a sequence of JsonLdRecords, + or a string representing an IRI, + which can be dereferenced to retrieve a valid JSON document.

+ +

When the value is a JsonLdRecord or sequence of JsonLdRecords, + the values are taken as their equivalent internal representation values, + where a JsonLdRecord is equivalent to a map, + and a sequence of JsonLdRecords is equivalent to an array + of maps. The map entries are converted to their equivalents + in [INFRA].

+
+ +

9.2 RDF Dataset Interfaces

+ +

The RdfDataset interface describes operations on an RDF dataset + used by the fromRdf() + and toRdf() methods + in the JsonLdProcessor interface. + The interface may be used for constructing a new RDF dataset, + which has a default graph accessible via the defaultGraph attribute.

+ + 
WebIDL[Exposed=JsonLd]
+interface RdfDataset {
+  constructor();
+  readonly attribute RdfGraph defaultGraph;
+  void add(USVString graphName, RdfGraph graph);
+  iterable<USVString?, RdfGraph>;
+};
+ +
add()
+
+

Adds an RdfGraph and its associated graph name to the RdfDataset. + Used by the Deserialize JSON-LD to RDF Algorithm.

+ +
+
graphName
+
The graph name associated with graph. + graphName MUST be a + well-formed IRI or blank node identifier. +
+
graph
+
The RdfGraph to add to the RdfDataset.
+
+
+
defaultGraph
+
Provides access to the default graph associated with the RDF dataset.
+
iterable
+
The value pairs to iterate over + are the list of graph name-graph pairs, + with the graph name being null + (for the default graph), + an IRI, + or blank node identifier + and graph an RdfGraph instance.
+ +

The RdfGraph interface describes operations on an RDF graph used by the fromRdf() + and toRdf() methods + in the JsonLdProcessor interface. + The interface may be used for constructing a new RDF graph, + which is composed of zero or more RdfTriple instances.

+ + 
WebIDL[Exposed=JsonLd]
+interface RdfGraph {
+  constructor();
+  void add(RdfTriple triple);
+  iterable<RdfTriple>;
+};
+ +
add()
+
+

Adds an RdfTriple to the RdfGraph. + Used by the Deserialize JSON-LD to RDF Algorithm.

+ +
+
triple
+
The RdfTriple to add to the RdfGraph.
+
+
+
iterable
+
A value iterator + over the RdfTriple instances associated with the graph. + Note that a given RdfTriple instance may appear in more than one graph + within a particular RdfDataset instance.
+ +

The RdfTriple interface describes an triple.

+ + 
WebIDL[Exposed=JsonLd]
+interface RdfTriple {
+  constructor();
+  readonly attribute USVString subject;
+  readonly attribute USVString predicate;
+  readonly attribute (USVString or RdfLiteral) _object;
+};
+ +
+
subject
+
An absolute IRI or blank node identifier + denoting the subject of the triple.
+
predicate
+
An absolute IRI denoting the predicate of the triple. + If used to represent a Generalized RDF Dataset, + it may also be a blank node identifier. +
Note
The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, as is the support for generalized RDF Datasets.
+
+
object
+
An absolute IRI, blank node identifier, or literal + denoting the object of the triple.
+
+ +

The RdfLiteral interface describes an RDF Literal.

+ + 
WebIDL[Exposed=JsonLd]
+interface RdfLiteral {
+  constructor();
+  readonly attribute USVString value;
+  readonly attribute USVString datatype;
+  readonly attribute USVString? language;
+};
+ +
+
value
+
The lexical value of the literal.
+
datatype
+
An absolute IRI denoting the datatype IRI of the literal. + If the value is rdf:langString, + language MUST be specified.
+
language
+
An optional language tag as defined by [BCP47]. + If this value is specified, datatype MUST be rdf:langString.
+
+
+ +

9.3 The JsonLdOptions Type

+ +

The JsonLdOptions type is used to pass various options to the + JsonLdProcessor methods.

+ + 
WebIDLdictionary JsonLdOptions {
+  USVString?             base = null;
+  boolean                compactArrays = true;
+  boolean                compactToRelative = true;
+  LoadDocumentCallback?  documentLoader = null;
+  (JsonLdRecord? or USVString) expandContext = null;
+  boolean                extractAllScripts = false;
+  boolean                frameExpansion = false;
+  boolean                ordered = false;
+  USVString              processingMode = "json-ld-1.1";
+  boolean                produceGeneralizedRdf = true;
+  USVString?             rdfDirection = null;
+  boolean                useNativeTypes = false;
+  boolean                useRdfType = false;
+};
+ +
base
+
The base IRI to use when expanding or compacting the document. + If set, this overrides the input document's IRI.
+
compactArrays
+
If set to true, the JSON-LD processor replaces arrays + with just one element with that element during compaction. + If set to false, + all arrays will remain arrays even if they have just one element. +
+
compactToRelative
+
Determines if IRIs are compacted + relative to the base option + or document location when compacting.
+
documentLoader
+
The callback of the loader to be used to retrieve remote documents and contexts, + implementing the LoadDocumentCallback. + If specified, it is used to retrieve remote documents and contexts; + otherwise, if not specified, the processor's built-in loader is used.
+
expandContext
+
A context that is used to initialize the active context when expanding a document.
+
extractAllScripts
+
If set to true, + when extracting JSON-LD script elements from HTML, + unless a specific fragment identifier is targeted, + extracts all encountered JSON-LD script elements using an array form, if necessary.
+
frameExpansion
+
Enables special frame processing rules for the Expansion Algorithm.
+
Enables special rules for the Serialize RDF as JSON-LD Algorithm + to use JSON-LD native types as values, where possible.
+
ordered
+
If set to true, + certain algorithm processing steps where indicated are ordered lexicographically. + If false, order is not considered in processing.
+
processingMode
+
Sets the processing mode. + If set to json-ld-1.0 or json-ld-1.1, + the implementation must 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 with json-ld + as they are reserved for future versions of this specification.
+
produceGeneralizedRdf
+
If set to true, the JSON-LD processor may emit + blank nodes for triple predicates, + otherwise they will be omitted. + Generalized RDF Datasets + are defined in [RDF11-CONCEPTS]. +
Note
The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, + as is the support for generalized RDF Datasets + and thus the produceGeneralizedRdf option may be also be removed.
+
+
rdfDirection
+
Determines how value objects containing a base direction + are transformed to and from RDF. +
    +
  • If set to i18n-datatype, an RDF literal is generated using a datatype IRI + based on https://www.w3.org/ns/i18n# with both the language tag (if present) + and base direction encoded. + When transforming from RDF, this datatype is decoded to create a value object + containing @language (if present) and @direction.
    • +
  • If set to compound-literal, a blank node is emitted instead of a literal, + where the blank node is the subject of rdf:value, rdf:direction, and rdf:language (if present) + properties. + When transforming from RDF, this object is decoded to create a value object + containing @language (if present) and @direction.
    • +
+
useNativeTypes
+
Causes the Serialize RDF as JSON-LD Algorithm + to use native JSON values in value objects avoiding the need for an explicitly @type.
+
useRdfType
+
Enables special rules for the Serialize RDF as JSON-LD Algorithm + causing rdf:type properties to be kept as IRIs in the output, rather than use @type.
+
+
+ +

9.4 Remote Document and Context Retrieval

+ +

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.

+ +
+

9.4.1 LoadDocumentCallback

+ +

The LoadDocumentCallback defines a callback that custom document loaders + have to implement to be used to retrieve remote documents and contexts. + The callback returns a Promise resolving to a RemoteDocument. + On failure, the Promise with a JsonLdError having an appropriate error code.

+ + 
WebIDLcallback LoadDocumentCallback = Promise<RemoteDocument> (
+  USVString url,
+  optional LoadDocumentOptions? options
+);
+ +
+
url
+
The URL of the remote document or context to load.
+
options
+
A set of options to determine + the behavior of the callback. See § 9.4.2 LoadDocumentOptions.
+
+ +

The following algorithm describes the default callback and places + requirements on implementations of the callback.

+ +
    +
  1. Create a new Promise promise and return it. + The following steps are then deferred.
    2. +
  2. Set document to the body retrieved from + the resource identified by url, + or by otherwise locating a resource associated with url. + When requesting remote documents the request MUST prefer Content-Type application/ld+json + followed by application/json. + +

    If requestProfile is set, + it MUST be added as a profile on application/ld+json.

    + +

    Processors MAY include other media types using a +json suffix as defined in [RFC6839].

    +
    3. +
  3. Set documentUrl to the location of the retrieved resource + considering redirections (exclusive of HTTP status 303 "See Other" redirects + as discussed in [cooluris]).
    4. +
  4. If the retrieved resource's Content-Type is not application/json + nor any media type with a +json suffix as defined in [RFC6839], + and the response has an HTTP Link Header [RFC8288] using the alternate link relation + with type application/ld+json, + set url to the associated href relative to the previous url + and restart the algorithm from step 2.
    5. +
  5. If the retrieved resource's Content-Type is application/json + or any media type with a +json suffix as defined in [RFC6839] + except application/ld+json, + and the response has an HTTP Link Header [RFC8288] using the http://www.w3.org/ns/json-ld#context link relation, + set contextUrl to the associated href. +

    If multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context link relation are found, + the promise is rejected with a JsonLdError whose code is set to multiple context link headers + and processing is terminated.

    +

    Processors MAY transform document to the internal representation.

    +
    Note

    The HTTP Link Header is ignored for documents served as application/ld+json, + text/html, or application/xhtml+xml.

    +
    6. +
  6. Otherwise, the retrieved document's Content-Type is neither + application/json, + application/ld+json, + nor any other media type using a + +json suffix as defined in [RFC6839]. + Reject the promise passing a loading document failed error.
    7. +
  7. Create a new RemoteDocument remote document using + url as documentUrl, + document as document, + the returned Content-Type (without parameters) as contentType, + any returned profile parameter, or null as profile, + and contextUrl, or null as contextUrl.
    8. +
  8. Resolve the promise with remote document.
    9. +
+ +
Note

A custom LoadDocumentCallback set via the + documentLoader option might be used + to maintain a local cache of well-known context documents or to implement + application-specific URL protocols.

+
+ +
+

9.4.2 LoadDocumentOptions

+ +

The LoadDocumentOptions type is used to pass various options + to the LoadDocumentCallback.

+ + 
WebIDLdictionary LoadDocumentOptions {
+  boolean  extractAllScripts = false;
+  USVString profile = null;
+  (USVString or sequence<USVString>) requestProfile = null;
+};
+ +
+
extractAllScripts
+
If set to true, + when extracting JSON-LD script elements from HTML, + unless a specific fragment identifier is targeted, + extracts all encountered JSON-LD script elements using an array form, if necessary.
+
profile
+
When the resulting contentType is text/html + or application/xhtml+xml, + this option determines the profile to use for selecting JSON-LD script elements.
+
requestProfile
+
One or more IRIs to use in the request as a profile parameter. + (See IANA Considerations in [JSON-LD11]).
+
+
+ +
+

9.4.3 RemoteDocument

+ +

The RemoteDocument type is used by a LoadDocumentCallback + to return information about a remote document or context.

+ + 
WebIDL[Exposed=JsonLd]
+interface RemoteDocument {
+  constructor();
+  readonly attribute USVString contentType;
+  readonly attribute USVString contextUrl;
+  attribute any document;
+  readonly attribute USVString documentUrl;
+  readonly attribute USVString profile;
+};
+ +
contentType
+
The Content-Type + of the loaded document, exclusive of any optional parameters.
+
contextUrl
+
If available, the value of the HTTP Link Header [RFC8288] + 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 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 is rejected + with a JsonLdError whose code is set to multiple context link headers.
+
document
+
The retrieved document. + This can either be the raw payload or the already parsed document.
+
documentUrl
+
The final URL of the loaded document. + This is important to handle HTTP redirects properly.
+
profile
+
The value of any profile parameter + retrieved as part of the original contentType.
+
+
+ +

9.5 HTML Content Algorithms

+
Note

This section describes optional features available + with a documentLoader supporting HTML script extraction.

+

Implementations of a documentLoader MAY support extracting JSON-LD from + script elements contained within an HTML [HTML] document. + This section describes the normative behavior of such processors. + Such a processor supports HTML script extraction.

+ +

9.5.1 Process HTML

+

This sections describe an extension to the algorithm specified + in LoadDocumentCallback to support extracting JSON-LD from HTML.

+ +

Step 2 is updated to add the following: A processor supporting HTML script extraction MUST include text/html at any preference level + and MAY include application/xhtml+xml at any preference level, + unless requestProfile is http://www.w3.org/ns/json-ld#context.

+ +

After step 5, add the following processing step: + Otherwise, if the retrieved resource's Content-Type is either text/html + or application/xhtml+xml:

+
    +
  1. Set documentUrl to the Document Base URL + of url, as defined in [HTML], + using the existing documentUrl as the document's URL. +
    2. +
  2. If the url parameter + contains a fragment identifier, + set source to the textContent + of the script element in document + having an id attribute + that matches the fragment identifier, after decoding percent encoded sequences. +

    If no such element is found, + or the located element is not a JSON-LD script element, + the promise is rejected with a JsonLdError whose code is set to loading document failed + and processing is terminated.

    +
    3. +
  3. Otherwise, if the profile + option is specified, + set source to the result of transforming the + textContent + of the first script element in document + having an type attribute + of application/ld+json along with the value of the + profile option, if found.
    4. +
  4. If source is still undefined and the extractAllScripts option is not present, or false, + set source to the textContent + of the first JSON-LD script element in document. +

    If no such element is found, + or the located element is not a JSON-LD script element, + the promise is rejected with a JsonLdError whose code is set to loading document failed + and processing is terminated.

    5. +
  5. If source is defined, + set document to the result of the + Extract Script Content algorithm, + using source, rejecting promise + with a JsonLdError whose code set from the result, if an error is detected + and processing is terminated. +
    6. +
  6. Otherwise, source is undefined. +
      +
    1. If the extractAllScripts option is not present, or false, + the promise is rejected with a JsonLdError whose code is set to loading document failed + and processing is terminated.
      2. +
    2. Otherwise, the extractAllScripts option is true. + Set document to a new empty array. + For each JSON-LD script element in input: +
        +
      1. Set source to its textContent.
        2. +
      2. Set script content to the result of the Extract Script Content algorithm, + using source, rejecting promise + with a JsonLdError whose code set from the result, if an error is detected + and processing is terminated.
        3. +
      3. If script content is an array, merge it to the end of document.
        4. +
      4. Otherwise, append script content to document.
        5. +
      +
      3. +
    +
    7. +
+
+ +
+

9.5.2 Extract Script Content Algorithm

+ +

The algorithm extracts the text content a + JSON-LD script element into a map or array of maps. + A JSON-LD script element is a script element + within an HTML [HTML] document with the type attribute set to + application/ld+json.

+ +

The algorithm takes a single required input variable: source, + the textContent of an HTML script element.

+ +
    +
  1. If source is not a valid JSON document, + an invalid script element has been detected, and processing is aborted.
    2. +
  2. Return the result of transforming source into the internal representation.
    3. +
+
+
+ +

9.6 Error Handling

+ +

This section describes the datatype definitions + used within the JSON-LD API for error handling.

+ +
+

9.6.1 JsonLdError

+ +

The JsonLdError type is used to report processing errors.

+ + 
WebIDLdictionary JsonLdError {
+  JsonLdErrorCode code;
+  USVString?      message = null;
+};
+ +
+
code
+
A string representing the particular error type, + as described in the various algorithms in this document.
+
message
+
An optional error message containing additional debugging information. + The specific contents of error messages are outside the scope of this specification.
+
+
+ +
+

9.6.2 JsonLdErrorCode

+

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

+ + 
WebIDLenum JsonLdErrorCode {
+    "colliding keywords",
+    "conflicting indexes",
+    "context overflow",
+    "cyclic IRI mapping",
+    "invalid @id value",
+    "invalid @import value",
+    "invalid @included value",
+    "invalid @index value",
+    "invalid @nest value",
+    "invalid @prefix value",
+    "invalid @propagate value",
+    "invalid @protected value",
+    "invalid @reverse value",
+    "invalid @version value",
+    "invalid base direction",
+    "invalid base IRI",
+    "invalid container mapping",
+    "invalid context entry",
+    "invalid context nullification",
+    "invalid default language",
+    "invalid IRI mapping",
+    "invalid JSON literal",
+    "invalid keyword alias",
+    "invalid language map value",
+    "invalid language mapping",
+    "invalid language-tagged string",
+    "invalid language-tagged value",
+    "invalid local context",
+    "invalid remote context",
+    "invalid reverse property map",
+    "invalid reverse property value",
+    "invalid reverse property",
+    "invalid scoped context",
+    "invalid script element",
+    "invalid set or list object",
+    "invalid term definition",
+    "invalid type mapping",
+    "invalid type value",
+    "invalid typed value",
+    "invalid value object value",
+    "invalid value object",
+    "invalid vocab mapping",
+    "IRI confused with prefix",
+    "keyword redefinition",
+    "loading document failed",
+    "loading remote context failed",
+    "multiple context link headers",
+    "processing mode conflict",
+    "protected term redefinition"
+};
+ +
colliding keywords
+
Two properties which expand to the same keyword have been detected. + This might occur if a keyword + and an alias thereof + are used at the same time.
+
conflicting indexes
+
Multiple conflicting indexes have been found for the same node.
+
context overflow
+
Maximum number of @context URLs exceeded.
+
cyclic IRI mapping
+
A cycle in IRI mappings has been detected.
+
invalid @id value
+
An @id entry was encountered whose value was not a string.
+
invalid @import value
+
An invalid value for @import has been found.
+
invalid @included value
+
An included block contains an invalid value.
+
invalid @index value
+
An @index entry was encountered whose value was not a string.
+
invalid @nest value
+
An invalid value for @nest has been found.
+
invalid @prefix value
+
An invalid value for @prefix has been found.
+
invalid @propagate value
+
An invalid value for @propagate has been found.
+
invalid @protected value
+
An invalid value for @protected has been found.
+
invalid @reverse value
+
An invalid value for an @reverse entry has been detected, + i.e., the value was not a map.
+
invalid @version value
+
The @version entry was used in a context + with an out of range value.
+
invalid base direction
+
The value of @direction is not "ltr", "rtl", + or null and thus invalid.
+
invalid base IRI
+
An invalid base IRI has been detected, i.e., + it is neither an IRI nor null.
+
invalid container mapping
+
An @container entry was encountered + whose value was not one of the following strings: + @list, + @set, + @language, + @index, + @id, + @graph, or + @type.
+
invalid context entry
+
An entry in a context is invalid due to processing mode incompatibility.
+
invalid context nullification
+
An attempt was made to nullify a context + containing protected term definitions.
+
invalid default language
+
The value of the default language is not a string + or null and thus invalid.
+
invalid IRI mapping
+
A local context contains a term + that has an invalid or missing IRI mapping.
+
invalid JSON literal
+
An invalid JSON literal was detected.
+
invalid keyword alias
+
An invalid keyword alias definition has been encountered.
+
invalid language map value
+
An invalid value in a language map has been detected. + It MUST be a string or an array of strings.
+
invalid language mapping
+
An @language entry in a term definition + was encountered whose value was neither a string + nor null and thus invalid.
+
invalid language-tagged string
+
A language-tagged string with an invalid language value was detected.
+
invalid language-tagged value
+
A number, true, or false + with an associated language tag was detected.
+
invalid local context
+
In invalid local context was detected.
+
invalid remote context
+
No valid context document has been found for a referenced remote context.
+
invalid reverse property
+
An invalid reverse property definition has been detected.
+
invalid reverse property map
+
An invalid reverse property map has been detected. + No keywords apart from @context + are allowed in reverse property maps.
+
invalid reverse property value
+
An invalid value for a reverse property has been detected. + The value of an inverse property must be a node object.
+
invalid scoped context
+
The local context + defined within a term definition + is invalid.
+
invalid script element
+
A script element in HTML input + which is the target of a fragment identifier + does not have an appropriate type attribute.
+
invalid set or list object
+
A set object or list object + with disallowed entries + has been detected.
+
invalid term definition
+
An invalid term definition has been detected.
+
invalid type mapping
+
An @type entry in a term definition + was encountered whose value could not be expanded to an IRI.
+
invalid type value
+
An invalid value for an @type entry has been detected, + i.e., the value was neither a string nor an array of strings.
+
invalid typed value
+
A typed value with an invalid type was detected.
+
invalid value object
+
A value object with disallowed entries has been detected.
+
invalid value object value
+
An invalid value for the @value entry of a value object + has been detected, + i.e., it is neither a scalar nor null.
+
invalid vocab mapping
+
An invalid vocabulary mapping has been detected, + i.e., it is neither an IRI nor null.
+
IRI confused with prefix
+
When compacting an IRI would result in an IRI + which could be confused with a compact IRI + (because its IRI scheme matches a term definition and it has no IRI authority).
+
keyword redefinition
+
A keyword redefinition has been detected.
+
loading document failed
+
The document could not be loaded or parsed as JSON.
+
loading remote context failed
+
There was a problem encountered loading a remote context.
+
multiple context link headers
+
Multiple HTTP Link Headers [RFC8288] + using the http://www.w3.org/ns/json-ld#context link relation + have been detected.
+
processing mode conflict
+
An attempt was made to change the processing mode + which is incompatible with the previous specified version.
+
protected term redefinition
+
An attempt was made to redefine a protected term.
+
+
+
+ +

10. Security Considerations

+

See, Security Considerations in [JSON-LD11].

+
+ +

11. Privacy Considerations

+

See, Privacy Considerations in [JSON-LD11].

+
+ +

12. Internationalization Considerations

+

See, Internationalization Considerations in [JSON-LD11].

+
+ +

A. IDL Index

This section is non-normative.

+
WebIDL/*
+ * The JsonLd interface is created to expose the JsonLdProcessor interface.
+ */
+[Global=JsonLd, Exposed=JsonLd]
+interface JsonLd {};
+
+[Exposed=JsonLd]
+interface JsonLdProcessor {
+  constructor();
+  static Promise<JsonLdRecord> compact(
+    JsonLdInput input,
+    optional JsonLdContext context = null,
+    optional JsonLdOptions options = {});
+  static Promise<sequence<JsonLdRecord>> expand(
+    JsonLdInput input,
+    optional JsonLdOptions options = {});
+  static Promise<JsonLdRecord> flatten(
+    JsonLdInput input,
+    optional JsonLdContext context = null,
+    optional JsonLdOptions options = {});
+  static Promise<sequence<JsonLdRecord>> fromRdf(
+    RdfDataset input,
+    optional JsonLdOptions options = {});
+  static Promise<RdfDataset> toRdf(
+    JsonLdInput input,
+    optional JsonLdOptions options = {});
+};
+
+typedef record<USVString, any> JsonLdRecord;
+
+typedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;
+
+typedef (JsonLdRecord or sequence<(JsonLdRecord or USVString)> or USVString) JsonLdContext;
+
+[Exposed=JsonLd]
+interface RdfDataset {
+  constructor();
+  readonly attribute RdfGraph defaultGraph;
+  void add(USVString graphName, RdfGraph graph);
+  iterable<USVString?, RdfGraph>;
+};
+
+[Exposed=JsonLd]
+interface RdfGraph {
+  constructor();
+  void add(RdfTriple triple);
+  iterable<RdfTriple>;
+};
+
+[Exposed=JsonLd]
+interface RdfTriple {
+  constructor();
+  readonly attribute USVString subject;
+  readonly attribute USVString predicate;
+  readonly attribute (USVString or RdfLiteral) _object;
+};
+
+[Exposed=JsonLd]
+interface RdfLiteral {
+  constructor();
+  readonly attribute USVString value;
+  readonly attribute USVString datatype;
+  readonly attribute USVString? language;
+};
+
+dictionary JsonLdOptions {
+  USVString?             base = null;
+  boolean                compactArrays = true;
+  boolean                compactToRelative = true;
+  LoadDocumentCallback?  documentLoader = null;
+  (JsonLdRecord? or USVString) expandContext = null;
+  boolean                extractAllScripts = false;
+  boolean                frameExpansion = false;
+  boolean                ordered = false;
+  USVString              processingMode = "json-ld-1.1";
+  boolean                produceGeneralizedRdf = true;
+  USVString?             rdfDirection = null;
+  boolean                useNativeTypes = false;
+  boolean                useRdfType = false;
+};
+
+callback LoadDocumentCallback = Promise<RemoteDocument> (
+  USVString url,
+  optional LoadDocumentOptions? options
+);
+
+dictionary LoadDocumentOptions {
+  boolean  extractAllScripts = false;
+  USVString profile = null;
+  (USVString or sequence<USVString>) requestProfile = null;
+};
+
+[Exposed=JsonLd]
+interface RemoteDocument {
+  constructor();
+  readonly attribute USVString contentType;
+  readonly attribute USVString contextUrl;
+  attribute any document;
+  readonly attribute USVString documentUrl;
+  readonly attribute USVString profile;
+};
+
+dictionary JsonLdError {
+  JsonLdErrorCode code;
+  USVString?      message = null;
+};
+
+enum JsonLdErrorCode {
+    "colliding keywords",
+    "conflicting indexes",
+    "context overflow",
+    "cyclic IRI mapping",
+    "invalid @id value",
+    "invalid @import value",
+    "invalid @included value",
+    "invalid @index value",
+    "invalid @nest value",
+    "invalid @prefix value",
+    "invalid @propagate value",
+    "invalid @protected value",
+    "invalid @reverse value",
+    "invalid @version value",
+    "invalid base direction",
+    "invalid base IRI",
+    "invalid container mapping",
+    "invalid context entry",
+    "invalid context nullification",
+    "invalid default language",
+    "invalid IRI mapping",
+    "invalid JSON literal",
+    "invalid keyword alias",
+    "invalid language map value",
+    "invalid language mapping",
+    "invalid language-tagged string",
+    "invalid language-tagged value",
+    "invalid local context",
+    "invalid remote context",
+    "invalid reverse property map",
+    "invalid reverse property value",
+    "invalid reverse property",
+    "invalid scoped context",
+    "invalid script element",
+    "invalid set or list object",
+    "invalid term definition",
+    "invalid type mapping",
+    "invalid type value",
+    "invalid typed value",
+    "invalid value object value",
+    "invalid value object",
+    "invalid vocab mapping",
+    "IRI confused with prefix",
+    "keyword redefinition",
+    "loading document failed",
+    "loading remote context failed",
+    "multiple context link headers",
+    "processing mode conflict",
+    "protected term redefinition"
+};
+ +

B. Open Issues

This section is non-normative.

+

The following is a list of issues open at the time of publication.

+
Issue 76: More compact @prefix defer-future-version

More compact @prefix.

+
Issue 94: Expansion concept "key's term definition" is unclear with compact IRI keys defer-future-version

Expansion concept "key's term definition" is unclear with compact IRI keys.

+
Issue 166: Relationship to the RDF/JS Dataset interface(s) defer-future-version

Relationship to the RDF/JS Dataset interface(s).

+
Issue 380: Expansion does not take property-scoped contexts for nested properties into account defer-future-versionspec:editorialtest:needs testswr:spec-updated-partial

Expansion does not take property-scoped contexts for nested properties into account.

+
Issue 391: Recursively nested properties and compaction defer-future-version

Recursively nested properties and compaction.

+

relative iri compaction.

+
+ +

C. Changes since 1.0 Recommendation of 16 January 2014

This section is non-normative.

+ +

Additionally, see § D. Changes since JSON-LD Community Group Final Report.

+
+ +

D. Changes since JSON-LD Community Group Final Report

This section is non-normative.

+ +
+
+

E. Changes since Candidate Release of 12 December 2019

This section is non-normative.

+
Note

All changes are editorial and do not affect the observable + behavior of the API nor the expected test results.

+ +
+
+

F. Changes since Candidate Release of 05 March 2020

This section is non-normative.

+
Note

All changes are editorial and do not affect the observable + behavior of the API nor the expected test results.

+ +
+
+

G. Changes since Proposed Recommendation Release of 7 May 2020

This section is non-normative.

+
    +
  • Removed remaining "at-risk" notes.
    • +
  • Update bibliographic reference for JCS to [RFC8785].
    • +
  • Changed [Exposed=(Window,Worker)] to [Exposed=JsonLd], + which is declared as a global interface in order to expose the JsonLdProcessor interface + for non-browser usage to address review suggestions.
    • +
+
+
+

H. Acknowledgements

This section is non-normative.

+

+ The editors would like to specially thank the following individuals for making significant + contributions to the authoring and editing of this specification: +

+ +
    +
  • Timothy Cole (University of Illinois at Urbana-Champaign)
    • +
  • Gregory Todd Williams (J. Paul Getty Trust)
    • +
  • Ivan Herman (W3C Staff)
    • +
  • Jeff Mixter (OCLC (Online Computer Library Center, Inc.))
    • +
  • David Lehn (Digital Bazaar)
    • +
  • David Newbury (J. Paul Getty Trust)
    • +
  • Robert Sanderson (J. Paul Getty Trust, chair)
    • +
  • Harold Solbrig (Johns Hopkins Institute for Clinical and Translational Research)
    • +
  • Simon Steyskal (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
    • +
  • A Soroka (Apache Software Foundation)
    • +
  • Ruben Taelman (Imec vzw)
    • +
  • Benjamin Young (Wiley, chair)
    • +
+ +

Additionally, the following people were members of the Working Group at the time of publication:

+ +
    +
  • Steve Blackmon (Apache Software Foundation)
    • +
  • Dan Brickley (Google, Inc.)
    • +
  • Newton Calegari (NIC.br - Brazilian Network Information Center)
    • +
  • Victor Charpenay (Siemens AG)
    • +
  • Sebastian Käbisch (Siemens AG)
    • +
  • Axel Polleres (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
    • +
  • Leonard Rosenthol (Adobe)
    • +
  • Jean-Yves ROSSI (CANTON CONSULTING)
    • +
  • Antoine Roulin (CANTON CONSULTING)
    • +
  • Manu Sporny (Digital Bazaar)
    • +
  • Clément Warnier de Wailly (CANTON CONSULTING)
    • +
+ +

+ A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons: Chris Webber, David Wood, Drummond Reed, Eleanor Joslin, Fabien Gandon, Herm Fisher, Jamie Pitts, Kim Hamilton Duffy, Niklas Lindström, Paolo Ciccarese, Paul Frazze, Paul Warren, Reto Gmür, Rob Trainer, Ted Thibodeau Jr., and Victor Charpenay. +

+ +
+ + + + +

I. References

+

I.1 + Normative references +

+
+
[BCP47]
Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47
[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[IEEE-754-2008]
IEEE 754-2008 Standard for Floating-Point Arithmetic. Institute of Electrical and Electronics Engineers. 2008. URL: http://standards.ieee.org/findstds/standard/754-2008.html
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON-LD10]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Marcus Langhaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/2014/REC-json-ld-20140116/
[JSON-LD11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11/
[JSON-LD11-FRAMING]
JSON-LD 1.1 Framing. Dave Longley; Gregg Kellogg; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11-framing/
[LINKED-DATA]
Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html
[promises-guide]
Writing Promise-Using Specifications. Domenic Denicola. W3C. 9 November 2018. TAG Finding. URL: https://www.w3.org/2001/tag/doc/promises-guide
[RDF-SCHEMA]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
[RDF11-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[RDF11-MT]
RDF 1.1 Semantics. Patrick Hayes; Peter Patel-Schneider. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-mt/
[RFC2045]
Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2045
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[RFC3987]
Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc3987
[RFC5234]
Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://tools.ietf.org/html/rfc5234
[RFC6839]
Additional Media Type Structured Syntax Suffixes. T. Hansen; A. Melnikov. IETF. January 2013. Informational. URL: https://tools.ietf.org/html/rfc6839
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259
[RFC8288]
Web Linking. M. Nottingham. October 2017. Proposed Standard. URL: https://tools.ietf.org/html/rfc8288
[Turtle]
RDF 1.1 Turtle. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/
[WEBIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/
+
+

I.2 + Informative references +

+
+
[cooluris]
Cool URIs for the Semantic Web. Leo Sauermann; Richard Cyganiak. W3C. 3 December 2008. W3C Note. URL: https://www.w3.org/TR/cooluris/
[JSON-LD10-API]
JSON-LD 1.0 Processing Algorithms And API. Marcus Langhaler; Gregg Kellogg; Manu Sporny. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/2014/REC-json-ld-api-20140116/
[RFC8785]
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman. Network Working Group. June 2020. Informational. URL: https://www.rfc-editor.org/rfc/rfc8785
+
\ No newline at end of file diff --git a/docs/standards/references/json-ld11.html b/docs/standards/references/json-ld11.html new file mode 100644 index 0000000..7072f1a --- /dev/null +++ b/docs/standards/references/json-ld11.html @@ -0,0 +1,13368 @@ + +JSON-LD 1.1 + + + + + + + + + +
+

JSON-LD 1.1

+

A JSON-based Serialization for Linked Data

+

+ W3C Recommendation + +

+
+
This version:
+ https://www.w3.org/TR/2020/REC-json-ld11-20200716/ +
Latest published version:
+ https://www.w3.org/TR/json-ld11/ +
+
Latest editor's draft:
https://w3c.github.io/json-ld-syntax/
+
Test suite:
https://w3c.github.io/json-ld-api/tests/
+
Implementation report:
+ https://w3c.github.io/json-ld-api/reports/ +
+ +
Previous version:
https://www.w3.org/TR/2020/PR-json-ld11-20200507/
+
Previous Recommendation:
https://www.w3.org/TR/2014/REC-json-ld-20140116/
+
Editors:
+
Gregg Kellogg (v1.0 and v1.1)
Pierre-Antoine Champin + (LIRIS - Université de Lyon) + (v1.1)
Dave Longley + (Digital Bazaar) + (v1.1)
+
+ Former editors: +
Manu Sporny + (Digital Bazaar) + (v1.0)
Markus Lanthaler + (Google) + (v1.0)
+
+ Authors: +
Manu Sporny + (Digital Bazaar) + (v1.0)
Dave Longley + (Digital Bazaar) + (v1.0 and v1.1)
Gregg Kellogg (v1.0 and v1.1)
Markus Lanthaler + (Google) + (v1.0)
Pierre-Antoine Champin + (LIRIS - Université de Lyon) + (v1.1)
Niklas Lindström (v1.0)
+
Participate:
+ GitHub w3c/json-ld-syntax +
+ File a bug +
+ Commit history +
+ Pull requests +
+
+

+ Please check the + errata for any errors or + issues reported since publication. +

+

+ See also + + translations. +

+

+ This document is also available in this non-normative format: + EPUB +

+

+ Copyright + © + 2010-2020 + + W3C® (MIT, + ERCIM, Keio, + Beihang). + W3C liability, + trademark and permissive document license rules + apply. +

+
+
+

Abstract

+

JSON is a useful data serialization and messaging format. + This specification defines JSON-LD 1.1, a JSON-based format to serialize + Linked Data. The syntax is designed to easily integrate into deployed + systems that already use JSON, and provides a smooth upgrade path from + JSON to JSON-LD. + It is primarily intended to be a way to use Linked Data in Web-based + programming environments, to build interoperable Web services, and to + store Linked Data in JSON-based storage engines.

+ +

This specification describes a superset of the features defined in + JSON-LD 1.0 [JSON-LD10] + and, except where noted, + documents created using the 1.0 version of this specification remain compatible with JSON-LD 1.1.

+
+ +

Status of This Document

This section describes the status of this + document at the time of its publication. Other documents may supersede + this document. A list of current W3C publications and the latest revision + of this technical report can be found in the + W3C technical reports index at + https://www.w3.org/TR/.

+

This document has been developed by the + JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.

+ +

There is a + live JSON-LD playground that is capable + of demonstrating the features described in this document.

+ +

This specification is intended to supersede the JSON-LD 1.0 [JSON-LD10] specification.

+ +

+ This document was published by the JSON-LD Working Group as a + Recommendation. + +

+ GitHub Issues are preferred for + discussion of this specification. + + Alternatively, you can send comments to our mailing list. + Please send them to + public-json-ld-wg@w3.org + (archives). + +

+ Please see the Working Group's + implementation report. +

+ This document has been reviewed by W3C Members, by software developers, and + by other W3C groups and interested parties, and is endorsed by the Director + as a W3C Recommendation. It is a stable document and may be used as + reference material or cited from another document. W3C's role in making the + Recommendation is to draw attention to the specification and to promote its + widespread deployment. This enhances the functionality and interoperability + of the Web. +

+ + This document was produced by a group + operating under the + W3C Patent Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + + +

+ This document is governed by the + 1 March 2019 W3C Process Document. +

+

Set of Documents

+

This document is one of three JSON-LD 1.1 Recommendations produced by the + JSON-LD Working Group:

+ + +
+
+ +
+

1. Introduction

This section is non-normative.

+ +

Linked Data [LINKED-DATA] is a way to create a network of + standards-based machine interpretable data across different documents and + Web sites. It allows an application to start at one piece of Linked Data, + and follow embedded links to other pieces of Linked Data that are hosted on + different sites across the Web.

+ +

JSON-LD is a lightweight syntax to serialize Linked Data in + JSON [RFC8259]. Its design allows existing JSON to be interpreted as + Linked Data with minimal changes. JSON-LD is primarily intended to be a + way to use Linked Data in Web-based programming environments, to build + interoperable Web services, and to store Linked Data in JSON-based storage engines. Since + JSON-LD is 100% compatible with JSON, the large number of JSON parsers and libraries + available today can be reused. In addition to all the features JSON provides, + JSON-LD introduces:

+ +
    +
  • a universal identifier mechanism for JSON objects + via the use of IRIs,
    • +
  • a way to disambiguate keys shared among different JSON documents by mapping + them to IRIs via a context,
    • +
  • a mechanism in which a value in a JSON object may refer + to a resource on a different site on the Web,
    • +
  • the ability to annotate strings with their language,
    • +
  • a way to associate datatypes with values such as dates and times,
    • +
  • and a facility to express one or more directed graphs, such as a social + network, in a single document.
    • +
+ +

JSON-LD is designed to be usable directly as JSON, with no knowledge of RDF + [RDF11-CONCEPTS]. It is also designed to be usable as RDF + in conjunction with other Linked Data technologies like SPARQL [SPARQL11-OVERVIEW]. + Developers who + require any of the facilities listed above or need to serialize an RDF graph + or Dataset in a JSON-based syntax will find JSON-LD of interest. People + intending to use JSON-LD with RDF tools will find it can be used as another + RDF syntax, as with [Turtle] and [TriG]. Complete details of how JSON-LD relates + to RDF are in section § 10. Relationship to RDF. +

+ +

The syntax is designed to not disturb already + deployed systems running on JSON, but provide a smooth upgrade path from + JSON to JSON-LD. Since the shape of such data varies wildly, JSON-LD + features mechanisms to reshape documents into a deterministic structure + which simplifies their processing.

+ +
+

1.1 How to Read this Document

This section is non-normative.

+ +

This document is a detailed specification for a serialization of Linked + Data in JSON. The document is primarily intended for the following audiences:

+ +
    +
  • Software developers who want to encode Linked Data in a variety of + programming languages that can use JSON
    • +
  • Software developers who want to convert existing JSON to JSON-LD
    • +
  • Software developers who want to understand the design decisions and + language syntax for JSON-LD
    • +
  • Software developers who want to implement processors and APIs for + JSON-LD
    • +
  • Software developers who want to generate or consume Linked Data, + an RDF graph, or an RDF Dataset in a JSON syntax
    • +
+ +

A companion document, the JSON-LD 1.1 Processing Algorithms and API specification + [JSON-LD11-API], specifies how to work with JSON-LD at a higher level by + providing a standard library interface for common JSON-LD operations.

+ +

To understand the basics in this specification you must first be familiar with + JSON, which is detailed in [RFC8259].

+ +

This document almost exclusively uses the term IRI + (Internationalized Resource Indicator) + when discussing hyperlinks. Many Web developers are more familiar with the + URL (Uniform Resource Locator) + terminology. The document also uses, albeit rarely, the URI + (Uniform Resource Indicator) + terminology. While these terms are often used interchangeably among + technical communities, they do have important distinctions from one + another and the specification goes to great lengths to try and use the + proper terminology at all times.

+ +

This document can highlight changes since the JSON-LD 1.0 version. + Select to changes.

+
+ +
+

1.2 Contributing

This section is non-normative.

+ +

There are a number of ways that one may participate in the development of + this specification:

+ +
    +
  • Technical discussion typically occurs on the working group mailing list: + public-json-ld-wg@w3.org
    • + +
  • The working group uses #json-ld + IRC channel is available for real-time discussion on irc.w3.org.
    • + +
  • The #json-ld + IRC channel is also available for real-time discussion on irc.freenode.net.
    • +
+ +
+ +
+

1.3 Typographical conventions

This section is non-normative.

+

The following typographic conventions are used in this specification:

+ +
+
markup
+ Markup (elements, attributes, properties), + machine processable values (string, characters, media types), + property name, + or a file name is in red-orange monospace font.
+
variable
+ A variable in pseudo-code or in an algorithm description is in italics.
+
definition
+ A definition of a term, to be used elsewhere in this or other specifications, + is in bold and italics.
+
definition reference
+ A reference to a definition in this document + is underlined and is also an active link to the definition itself.
+
markup definition reference
+ A references to a definition in this document, + when the reference itself is also a markup, is underlined, + red-orange monospace font, and is also an active link to the definition itself.
+
external definition reference
+ A reference to a definition in another document + is underlined, in italics, and is also an active link to the definition itself.
+
markup external definition reference
+ A reference to a definition in another document, + when the reference itself is also a markup, + is underlined, in italics red-orange monospace font, + and is also an active link to the definition itself.
+
hyperlink
+ A hyperlink is underlined and in blue.
+
[reference]
+ A document reference (normative or informative) is enclosed in square brackets + and links to the references section.
+
Changes from Recommendation
+ Sections or phrases changed from the previous Recommendation + may be highlighted using a control + in § 1.1 How to Read this Document.
+
+ +
Note

Notes are in light green boxes with a green left border and with a "Note" header in green. + Notes are always informative.

+ +
+
+ Example 1 + 
Examples are in light khaki boxes, with khaki left border,
+and with a numbered "Example" header in khaki.
+Examples are always informative. The content of the example is in monospace font and may be syntax colored.
+
+Examples may have tabbed navigation buttons
+to show the results of transforming an example into other representations.
+
+
+
+ +
+

1.4 Terminology

This section is non-normative.

+ +

This document uses the following terms as defined in external specifications + and defines terms specific to JSON-LD.

+ +

Terms imported from Other Specifications

+

Terms imported from ECMAScript Language Specification [ECMASCRIPT], The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], Infra Standard [INFRA], and Web IDL [WEBIDL]

+
array
+ In the JSON serialization, + an array structure is represented as square brackets surrounding zero or more values. + Values are separated by commas. + In the internal representation, + a list (also called an array) is an ordered collection of zero or more values. + While JSON-LD uses the same array representation as JSON, + the collection is unordered by default. + While order is preserved in regular JSON arrays, + it is not in regular JSON-LD arrays unless specifically defined + (see the Sets and Lists section of JSON-LD 1.1.
+
boolean
+ The values true and false that are used + to express one of two possible states.
+
JSON object
+ In the JSON serialization, + an object structure + is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members). + A name is a string. + A single colon comes after each name, + separating the name from the value. + A single comma separates a value from a following name. + In JSON-LD the names in an object must be unique. +

In the internal representation a JSON object is described as a + map (see [INFRA]), + composed of entries with key/value pairs.

+

In the Application Programming Interface, + a map is described using a [WEBIDL] record.

+
null
+ The use of the null value within JSON-LD + is used to ignore or reset values. + A map entry in the @context where the value, + or the @id of the value, is null, + explicitly decouples a term's association with an IRI. + A map entry in the body of a JSON-LD document + whose value is null + has the same meaning as if the map entry was not defined. + If @value, @list, or @set is set to null in expanded form, + then the entire JSON object is ignored.
+
number
+ In the JSON serialization, a number + is similar to that used in most programming languages, + except that the octal and hexadecimal formats are not used and that leading zeros are not allowed. + In the internal representation, + a number is equivalent to either a long + or double, + depending on if the number has a non-zero fractional part (see [WEBIDL]).
+
scalar
+ A scalar is either a string, number, true, or false.
+
string
+ A string + is a sequence of zero or more Unicode (UTF-8) characters, + wrapped in double quotes, using backslash escapes (if necessary). + A character is represented as a single character string.
+ +

Terms imported from Internationalized Resource Identifiers (IRIs) [RFC3987]

+
IRI
+ The absolute form of an IRI containing a scheme along with a path + and optional query and fragment segments.
+
IRI reference
+ Denotes the common usage of an Internationalized Resource Identifier. + An IRI reference may be absolute or + relative. + However, the "IRI" that results from such a reference only includes absolute IRIs; + any relative IRI references are resolved to their absolute form.
+
relative IRI reference
+ A relative IRI reference is an IRI reference that is relative to some other IRI, + typically the base IRI of the document. + Note that properties, + values of @type, + and values of terms defined to be vocabulary relative + are resolved relative to the vocabulary mapping, + not the base IRI.
+ +

Terms imported from RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS], RDF Schema 1.1 [RDF-SCHEMA], and Linked Data Design Issues [LINKED-DATA]

+
base IRI
+ The base IRI is an IRI established in the context, + or is based on the JSON-LD document location. + The base IRI is used to turn relative IRI references into IRIs.
+
blank node
+ A node in a graph that is neither an IRI, + nor a literal. + A blank node does not contain + a de-referenceable identifier because it is either ephemeral in nature + or does not contain information that needs to be linked to from outside of the linked data graph. + In JSON-LD, + a blank node is assigned an identifier starting with the prefix _:.
+
blank node identifier
+ A blank node identifier + is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document. + Blank node identifiers begin with _:.
+
dataset
+ A dataset + representing a collection of RDF graphs + including exactly one default graph and zero or more named graphs.
+
datatype IRI
+ A datatype IRI is an IRI identifying a datatype that determines how the lexical form maps to a + literal value.
+
default graph
+ The default graph of a dataset is an RDF graph having no name, which may be empty.
+
graph name
+ The IRI or blank node identifying a named graph.
+
language-tagged string
+ A language-tagged string + consists of a string and a non-empty language tag + as defined by [BCP47]. + The language tag must be well-formed + according to section 2.2.9 Classes of Conformance of [BCP47]. + Processors may normalize language tags to lowercase. +
+
Linked Data
+ A set of documents, each containing a representation of a linked data graph or dataset.
+
list
+ A list is an ordered sequence of IRIs, blank nodes, and literals.
+
literal
+ An object expressed as a value such as a string or number. + Implicitly or explicitly includes a datatype IRI and, if the datatype is rdf:langString, an optional language tag.
+
named graph
+ A named graph + is a linked data graph that is identified by an IRI or blank node.
+
node
+ A node in an RDF graph, either the subject and object of at least one triple. + Note that a node can play both roles (subject and object) in a graph, even in the same triple.
+
object
+ An object is a node in a linked data graph + with at least one incoming edge.
+
property
+ The name of a directed-arc in a linked data graph. + Every property is directional + and is labeled with an IRI or a blank node identifier. + Whenever possible, a property should be labeled with an IRI. +
Note
The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD.
+ Also, see predicate in [RDF11-CONCEPTS].
+
RDF graph
+ A labeled directed graph, + i.e., a set of nodes connected by directed-arcs. + Also called linked data graph. +
+
resource
+ A resource denoted by an IRI, a blank node or literal representing something in the world (the "universe of discourse").
+
subject
+ A subject is a node in a linked data graph + with at least one outgoing edge, + related to an object node through a property.
triple
+ A component of an RDF graph including a subject, predicate, and object, which represents + a node-arc-node segment of an RDF graph.
+
+
+ +

JSON-LD Specific Term Definitions

+
active context
+ A context that is used to resolve terms + while the processing algorithm is running.
+
base direction
+ The base direction is the direction used when a string does not have a direction associated with it directly. + It can be set in the context using the @direction key + whose value must be one of the strings "ltr", "rtl", or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description. +
+
compact IRI
+ A compact IRI has the form of prefix:suffix + and is used as a way of expressing an IRI without needing to define separate term definitions + for each IRI contained within a common vocabulary identified by prefix.
+
context
+ A set of rules for interpreting a JSON-LD document + as described in the The Context section of JSON-LD 1.1, + and normatively specified in the Context Definitions section of JSON-LD 1.1. +
+
default language
+ The default language is the language used when a string does not have a language associated with it directly. + It can be set in the context using the @language key + whose value must be a string representing a [BCP47] language code or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description. +
+
default object
+ A default object is a map that has a @default key.
+
embedded context
+ An embedded context is a context which appears + as the @context entry of one of the following: + a node object, a value object, a graph object, a list object, + a set object, the value of a nested properties, + or the value of an expanded term definition. + Its value may be a map for a context definition, + as an IRI, or as an array combining either of the above. +
+
expanded term definition
+ An expanded term definition is a term definition + where the value is a map + containing one or more keyword keys to define the associated IRI, + if this is a reverse property, + the type associated with string values, and a container mapping. + See the Expanded Term Definition section of JSON-LD 1.1 for a normative description. +
+
frame
+ A JSON-LD document, + which describes the form for transforming another JSON-LD document + using matching and embedding rules. + A frame document allows additional keywords and certain map entries + to describe the matching and transforming process.
+
frame object
+ A frame object is a map element within a frame + which represents a specific portion of the frame matching either + a node object or a value object + in the input. + See the Frame Objects section of JSON-LD 1.1 for a normative description. +
+
graph object
+ A graph object represents a named graph + as the value of a map entry within a node object. + When expanded, a graph object must have an @graph entry, + and may also have @id, and @index entries. + A simple graph object + is a graph object which does not have an @id entry. + Note that node objects may have a @graph entry, + but are not considered graph objects if they include any other entries. + A top-level object consisting of @graph is also not a graph object. + Note that a node object may also represent a named graph it it includes other properties. + See the Graph Objects section of JSON-LD 1.1 for a normative description. +
+
id map
+ An id map is a map value of a term + defined with @container set to @id. + The values of the id map must be node objects, + and its keys are interpreted as IRIs representing + the @id of the associated node object. + If a value in the id map contains a key expanding to @id, + its value must be equivalent to the referencing key in the id map. + See the Id Maps section of JSON-LD 1.1 for a normative description. +
+
implicitly named graph
+ A named graph created from the value of a map entry + having an expanded term definition + where @container is set to @graph.
+
included block
+ An included block is an entry in a node object where the key is either @included or an alias of @included + and the value is one or more node objects. + See the Included Blocks section of JSON-LD 1.1 for a normative description. +
+
index map
+ An index map is a map value of a term + defined with @container set to @index, + whose values must be any of the following types: + string, + number, + true, + false, + null, + node object, + value object, + list object, + set object, or + an array of zero or more of the above possibilities. + See the Index Maps section in JSON-LD 1.1 for a formal description. +
+
JSON literal
+ A JSON literal is a literal where the associated datatype IRI is rdf:JSON. + In the value object representation, the value of @type is @json. + JSON literals represent values which are valid JSON [RFC8259]. + See the The rdf:JSON Datatype section in JSON-LD 1.1 for a normative description. +
+
JSON-LD document
+ A JSON-LD document is a serialization of + an RDF dataset. + See the JSON-LD Grammar section in JSON-LD 1.1 for a formal description. +
+
JSON-LD internal representation
+ The JSON-LD internal representation + is the result of transforming a JSON syntactic structure + into the core data structures suitable for direct processing: + arrays, maps, strings, numbers, booleans, and null.
+
JSON-LD Processor
+ A JSON-LD Processor is a system which can perform the algorithms defined in JSON-LD 1.1 Processing Algorithms and API. + See the Conformance section in JSON-LD 1.1 API for a formal description. +
+
JSON-LD value
+ A JSON-LD value is a string, + a number, + true or false, + a typed value, + or a language-tagged string. + It represents an RDF literal. +
+
keyword
+ A string that is specific to JSON-LD, + described in the Syntax Tokens and Keywords section of JSON-LD 1.1, + and normatively specified in the Keywords section of JSON-LD 1.1, +
+
language map
+ An language map is a map value of a term + defined with @container set to @language, + whose keys must be strings representing [BCP47] language codes + and the values must be any of the following types: + null, + string, or + an array of zero or more of the above possibilities. + See the Language Maps section of JSON-LD 1.1 for a normative description. +
+
list object
+ A list object is a map that has a @list key. + It may also have an @index key, but no other entries. + See the Lists and Sets section of JSON-LD 1.1 for a normative description. +
+
local context
+ A context that is specified with a map, + specified via the @context keyword.
+
nested property
+ A nested property is a key in a node object + whose value is a map containing entries which are treated as if they were values of the node object. + The nested property itself is semantically meaningless and used only to create a sub-structure within a node object. + See the Property Nesting section of JSON-LD 1.1 for a normative description. +
+
node object
+ A node object represents zero or more properties of a node in the graph + serialized by the JSON-LD document. + A map is a node object + if it exists outside of the JSON-LD context and: +
    +
  • it does not contain the @value, @list, or @set keywords, or
    • +
  • it is not the top-most map in the JSON-LD document + consisting of no other entries than @graph and @context.
    • +
+ The entries of a node object whose keys are not keywords are also called properties of the node object. + See the Node Objects section of JSON-LD 1.1 for a normative description. +
+
node reference
+ A node object used to reference a node having only the @id key.
+
prefix
+ A prefix is the first component of a compact IRI + which comes from a term that maps to a string that, + when prepended to the suffix of the compact IRI, + results in an IRI.
+
processing mode
+ The processing mode defines how a JSON-LD document is processed. + By default, all documents are assumed to be conformant with this specification. + By defining a different version using the @version entry in a context, + publishers can ensure that processors conformant with JSON-LD 1.0 [JSON-LD10] + will not accidentally process JSON-LD 1.1 documents, possibly creating a different output. + The API provides an option for setting the processing mode to json-ld-1.0, + which will prevent JSON-LD 1.1 features from being activated, + or error if @version entry in a context is explicitly set to 1.1. + This specification extends JSON-LD 1.0 + via the json-ld-1.1 processing mode.
+
scoped context
+ A scoped context is part of an expanded term definition using the + @context entry. It has the same form as an embedded context. + When the term is used as a type, it defines a type-scoped context, + when used as a property it defines a property-scoped context. +
+
set object
+ A set object is a map that has an @set entry. + It may also have an @index key, but no other entries. + See the Lists and Sets section of JSON-LD 1.1 for a normative description. +
+
term
+ A term is a short word defined in a context + that may be expanded to an IRI. + See the Terms section of JSON-LD 1.1 for a normative description. +
+
term definition
+ A term definition is an entry in a context, + where the key defines a term + which may be used within a map + as a key, type, or elsewhere that a string is interpreted as a vocabulary item. + Its value is either a string (simple term definition), + expanding to an IRI, + or a map (expanded term definition). +
+
type map
+ A type map is a map value of a term + defined with @container set to @type, + whose keys are interpreted as IRIs + representing the @type of the associated node object; + the value must be a node object, or array of node objects. + If the value contains a term expanding to @type, + its values are merged with the map value when expanding. + See the Type Maps section of JSON-LD 1.1 for a normative description. +
+
typed value
+ A typed value consists of a value, + which is a string, + and a type, + which is an IRI.
+
value object
+ A value object is a map that has an @value entry. + See the Value Objects section of JSON-LD 1.1 for a normative description.
+
vocabulary mapping
+ The vocabulary mapping is set in the context using the @vocab key + whose value must be an IRI, a compact IRI, a term, or null. + See the Context Definitions section of JSON-LD 1.1 for a normative description.
+
+
+
+ +
+

1.5 Design Goals and Rationale

This section is non-normative.

+ +

JSON-LD satisfies the following design goals:

+ +
+
Simplicity
+
No extra processors or software libraries are necessary to use JSON-LD + in its most basic form. The language provides developers with a very easy + learning curve. Developers not concerned with Linked Data only need to understand JSON, + and know to include but ignore the @context property, + to use the basic functionality in JSON-LD.
+
Compatibility
+
A JSON-LD document is always a valid JSON document. This ensures that + all of the standard JSON libraries work seamlessly with JSON-LD documents.
+
Expressiveness
+
The syntax serializes labeled directed graphs. This ensures that almost + every real world data model can be expressed.
+
Terseness
+
The JSON-LD syntax is very terse and human readable, requiring as + little effort as possible from the developer.
+
Zero Edits, most of the time
+
JSON-LD ensures a smooth and simple transition from existing + JSON-based systems. In many cases, + zero edits to the JSON document and the addition of one line to the HTTP response + should suffice (see § 6.1 Interpreting JSON as JSON-LD). + This allows organizations that have + already deployed large JSON-based infrastructure to use JSON-LD's features + in a way that is not disruptive to their day-to-day operations and is + transparent to their current customers. However, there are times where + mapping JSON to a graph representation is a complex undertaking. + In these instances, rather than extending JSON-LD to support + esoteric use cases, we chose not to support the use case. While Zero + Edits is a design goal, it is not always possible without adding + great complexity to the language. JSON-LD focuses on simplicity when + possible.
+
Usable as RDF
+
JSON-LD is usable by developers as + idiomatic JSON, with no need to understand RDF [RDF11-CONCEPTS]. + JSON-LD is also usable as RDF, so people intending to use JSON-LD + with RDF tools will find it can be used like any other RDF syntax. + Complete details of how JSON-LD relates to RDF are in section + § 10. Relationship to RDF.
+
+
+ +
+

1.6 Data Model Overview

This section is non-normative.

+ +

Generally speaking, the data model described by a JSON-LD document is a labeled, directed graph. + The graph contains nodes, which are connected by directed-arcs. + A node is either a resource with properties, or the data values of those properties including + strings, numbers, typed values (like dates and times) and IRIs.

+

Within a directed graph, nodes are resources, and may + be unnamed, i.e., not identified by an IRI; + which are called blank nodes, + and may be identified using a blank node identifier. + These identifiers may be required to represent a fully connected graph + using a tree structure, such as JSON, but otherwise have no + intrinsic meaning. + Literal values, such as strings and numbers, are also considered resources, + and JSON-LD distinguishes between node objects and value objects to distinguish between the different + kinds of resource.

+

This simple data model is incredibly + flexible and powerful, capable of modeling almost any kind of + data. For a deeper explanation of the data model, see + section § 8. Data Model.

+ +

Developers who are familiar with Linked Data technologies will + recognize the data model as the RDF Data Model. To dive deeper into how + JSON-LD and RDF are related, see + section § 10. Relationship to RDF.

+ +

At the surface level, a JSON-LD document is simply + JSON, detailed in [RFC8259]. + For the purpose of describing the core data structures, + this is limited to arrays, maps (the parsed version of a JSON Object), + strings, numbers, booleans, and null, + called the JSON-LD internal representation. + This allows surface syntaxes other than JSON + to be manipulated using the same algorithms, when the syntax maps + to equivalent core data structures.

+
Note

Although not discussed in this specification, + parallel work using YAML Ain’t Markup Language (YAML™) Version 1.2 [YAML] + and binary representations such as Concise Binary Object Representation (CBOR) [RFC7049] + could be used to map into the internal representation, allowing + the JSON-LD 1.1 API [JSON-LD11-API] to operate as if the source was a + JSON document.

+
+ +
+

1.7 Syntax Tokens and Keywords

This section is non-normative.

+ +

JSON-LD specifies a number of syntax tokens and keywords + that are a core part of the language. + A normative description of the keywords is given in § 9.16 Keywords. +

+ +
:
+ The separator for JSON keys and values that use compact IRIs.
+
@base
+
Used to set the base IRI against which to resolve those relative IRI references + which are otherwise interpreted relative to the document. + This keyword is described in § 4.1.3 Base IRI.
+
@container
+
Used to set the default container type for a term. + This keyword is described in the following sections: +
+
@context
+
Used to define the short-hand names that are used throughout a JSON-LD + document. These short-hand names are called terms and help + developers to express specific identifiers in a compact manner. The + @context keyword is described in detail in + § 3.1 The Context.
+
@direction
+
Used to set the base direction of a JSON-LD value, + which are not typed values (e.g. strings, or language-tagged strings). + This keyword is described in + § 4.2.4 String Internationalization.
+
@graph
Used to express a graph. + This keyword is described in § 4.9 Named Graphs.
+
@id
+
Used to uniquely identify node objects that are being described in the document + with IRIs or + blank node identifiers. This keyword + is described in § 3.3 Node Identifiers. + A node reference is a node object containing only the @id property, + which may represent a reference to a node object found elsewhere in the document.
+
@import
+ Used in a context definition to load an external context + within which the containing context definition is merged. + This can be useful to add JSON-LD 1.1 features to JSON-LD 1.0 contexts.
+
@included
+ Used in a top-level node object to define an included block, + for including secondary node objects within another node object. +
@index
+
Used to specify that a container is used to index information and + that processing should continue deeper into a JSON data structure. + This keyword is described in § 4.6.1 Data Indexing.
+
@json
+ Used as the @type value of a JSON literal. + This keyword is described in § 4.2.2 JSON Literals. +
+
@language
+
Used to specify the language for a particular string value or the default + language of a JSON-LD document. This keyword is described in + § 4.2.4 String Internationalization.
+
@list
+
Used to express an ordered set of data. + This keyword is described in § 4.3.1 Lists.
+
@nest
Used to define a property of a node object that groups together properties of that node, but is not an edge in the graph.
+
@none
Used as an index value + in an index map, id map, language map, type map, or elsewhere where a map is + used to index into other values, when the indexed node does not have the feature being indexed.
+
@prefix
+ With the value true, allows this term to be used to construct a compact IRI + when compacting. + With the value false prevents the term from being used to construct a compact IRI. + Also determines if the term will be considered when expanding compact IRIs.
+
@propagate
+ Used in a context definition to change the scope of that context. + By default, it is true, + meaning that contexts propagate across node objects + (other than for type-scoped contexts, which default to false). + Setting this to false causes term definitions created within that context + to be removed when entering a new node object.
+
@protected
+ Used to prevent term definitions of a context to be overridden by other contexts. + This keyword is described in § 4.1.11 Protected Term Definitions. +
@reverse
+
Used to express reverse properties. This keyword is described in + § 4.8 Reverse Properties.
+
@set
+
Used to express an unordered set of data and to ensure that values are always + represented as arrays. This keyword is described in + § 4.3.2 Sets.
+
@type
+
Used to set the type of a node or the datatype of a typed value. + This keyword is described further in § 3.5 Specifying the Type + and § 4.2.1 Typed Values. +
Note
The use of @type to define a type for both + node objects and value objects addresses the basic need to type data, + be it a literal value or a more complicated resource. + Experts may find the overloaded use of the @type keyword for both purposes concerning, + but should note that Web developer usage of this feature over multiple years + has not resulted in its misuse due to the far less frequent use of @type + to express typed literal values. +
+
+
@value
+
Used to specify the data that is associated with a particular + property in the graph. This keyword is described in + § 4.2.4 String Internationalization and + § 4.2.1 Typed Values.
+
@version
+ Used in a context definition to set the processing mode. + New features since JSON-LD 1.0 [JSON-LD10] described in this specification are + not available when processing mode has been explicitly set to + json-ld-1.0. +
Note
Within a context definition @version takes the specific value 1.1, not + "json-ld-1.1", as a JSON-LD 1.0 processor may accept a string value for @version, + but will reject a numeric value.
+
Note
The use of 1.1 for the value of @version is intended to + cause a JSON-LD 1.0 processor to stop processing. + Although it is clearly meant to be related to JSON-LD 1.1, it does not + otherwise adhere to the requirements for Semantic Versioning.
+
+
@vocab
+
Used to expand properties and values in @type with a common prefix + IRI. This keyword is described in § 4.1.2 Default Vocabulary.
+
+ +

All keys, keywords, and values in JSON-LD are case-sensitive.

+
+
+ +

2. Conformance

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. +

+ The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+

A JSON-LD document complies with this specification if it follows + the normative statements in appendix § 9. JSON-LD Grammar. JSON documents + can be interpreted as JSON-LD by following the normative statements in + § 6.1 Interpreting JSON as JSON-LD. For convenience, normative + statements for documents are often phrased as statements on the properties of the document.

+ +

This specification makes use of the following namespace prefixes:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrefixIRI
dc11http://purl.org/dc/elements/1.1/
dctermshttp://purl.org/dc/terms/
credhttps://w3id.org/credentials#
foafhttp://xmlns.com/foaf/0.1/
geojsonhttps://purl.org/geojson/vocab#
provhttp://www.w3.org/ns/prov#
i18nhttps://www.w3.org/ns/i18n#
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#
schemahttp://schema.org/
skoshttp://www.w3.org/2004/02/skos/core#
xsdhttp://www.w3.org/2001/XMLSchema#
+ +

These are used within this document as part of a compact IRI + as a shorthand for the resulting IRI, such as dcterms:title + used to represent http://purl.org/dc/terms/title.

+
+ +
+

3. Basic Concepts

This section is non-normative.

+ +

JSON [RFC8259] is a lightweight, language-independent data interchange format. + It is easy to parse and easy to generate. However, it is difficult to integrate JSON + from different sources as the data may contain keys that conflict with other + data sources. Furthermore, JSON has no + built-in support for hyperlinks, which are a fundamental building block on + the Web. Let's start by looking at an example that we will be using for the + rest of this section:

+ +
+
+ Example 2: Sample JSON document + 
{
+  "name": "Manu Sporny",
+  "homepage": "http://manu.sporny.org/",
+  "image": "http://manu.sporny.org/images/manu.png"
+}
+
+ +

It's obvious to humans that the data is about a person whose + name is "Manu Sporny" + and that the homepage property contains the URL of that person's homepage. + A machine doesn't have such an intuitive understanding and sometimes, + even for humans, it is difficult to resolve ambiguities in such representations. This problem + can be solved by using unambiguous identifiers to denote the different concepts instead of + tokens such as "name", "homepage", etc.

+ +

Linked Data, and the Web in general, uses IRIs + (Internationalized Resource Identifiers as described in [RFC3987]) for unambiguous + identification. The idea is to use IRIs + to assign unambiguous identifiers to data that may be of use to other developers. + It is useful for terms, + like name and homepage, to expand to IRIs + so that developers don't accidentally step on each other's terms. Furthermore, developers and + machines are able to use this IRI (by using a web browser, for instance) to go to + the term and get a definition of what the term means. This process is known as IRI + dereferencing.

+ +

Leveraging the popular schema.org vocabulary, + the example above could be unambiguously expressed as follows:

+ + + +

In the example above, every property is unambiguously identified by an IRI and all values + representing IRIs are explicitly marked as such by the + @id keyword. While this is a valid JSON-LD + document that is very specific about its data, the document is also overly verbose and difficult + to work with for human developers. To address this issue, JSON-LD introduces the notion + of a context as described in the next section.

+ +

This section only covers the most basic features of JSON-LD. More advanced features, + including typed values, indexed values, and named graphs, + can be found in § 4. Advanced Concepts.

+ + +
+

3.1 The Context

This section is non-normative.

+ +

When two people communicate with one another, the conversation takes + place in a shared environment, typically called + "the context of the conversation". This shared context allows the + individuals to use shortcut terms, like the first name of a mutual friend, + to communicate more quickly but without losing accuracy. A context in + JSON-LD works in the same way. It allows two applications to use shortcut + terms to communicate with one another more efficiently, but without + losing accuracy.

+ +

Simply speaking, a context is used to map terms to IRIs. + Terms are case sensitive and most valid strings that are not reserved JSON-LD keywords + can be used as a term. + Exceptions are the empty string "" and strings that have the form + of a keyword (i.e., starting with "@" followed exclusively by one or more ALPHA characters (see [RFC5234])), which must not be used as terms. + Strings that have the form of + an IRI (e.g., containing a ":") should not be used as terms.

+ +

For the sample document in the previous section, a context would + look something like this:

+ +
+
+ Example 4: Context for the sample document in the previous section + 
{
+  "@context": {
+    "name": "http://schema.org/name",
+    ↑ This means that 'name' is shorthand for 'http://schema.org/name'
+    "image": {
+      "@id": "http://schema.org/image",
+      ↑ This means that 'image' is shorthand for 'http://schema.org/image'
+      "@type": "@id"
+      ↑ This means that a string value associated with 'image'
+        should be interpreted as an identifier that is an IRI
+    },
+    "homepage": {
+      "@id": "http://schema.org/url",
+      ↑ This means that 'homepage' is shorthand for 'http://schema.org/url'
+      "@type": "@id"
+      ↑ This means that a string value associated with 'homepage'
+        should be interpreted as an identifier that is an IRI 
+    }
+  }
+}
+
+ +

As the context above shows, the value of a term definition can + either be a simple string, mapping the term to an IRI, + or a map.

+ +

A context is introduced using an entry with the key @context and may + appear within a node object or a value object.

+ +

When an entry with a term key has a map value, the map is called + an expanded term definition. The example above specifies that + the values of image and homepage, if they are + strings, are to be interpreted as + IRIs. Expanded term definitions + also allow terms to be used for index maps + and to specify whether array values are to be + interpreted as sets or lists. + Expanded term definitions may + be defined using IRIs or + compact IRIs as keys, which is + mainly used to associate type or language information with an + IRIs or compact IRI.

+ +

Contexts can either be directly embedded + into the document (an embedded context) or be referenced using a URL. + Assuming the context document in the previous + example can be retrieved at https://json-ld.org/contexts/person.jsonld, + it can be referenced by adding a single line and allows a JSON-LD document to + be expressed much more concisely as shown in the example below:

+ + + +

The referenced context not only specifies how the terms map to + IRIs in the Schema.org vocabulary but also + specifies that string values associated with + the homepage and image property + can be interpreted as an IRI ("@type": "@id", + see § 3.2 IRIs for more details). This information allows developers + to re-use each other's data without having to agree to how their data will interoperate + on a site-by-site basis. External JSON-LD context documents may contain extra + information located outside of the @context key, such as + documentation about the terms declared in the + document. Information contained outside of the @context value + is ignored when the document is used as an external JSON-LD context document.

+ +

A remote context may also be referenced using a relative URL, + which is resolved relative to the location of the document containing the reference. + For example, if a document were located at http://example.org/document.jsonld + and contained a relative reference to context.jsonld, + the referenced context document would be found relative at http://example.org/context.jsonld.

+ +
+
+ Example 6: Loading a relative context + 
{
+  "@context": "context.jsonld",
+  "name": "Manu Sporny",
+  "homepage": "http://manu.sporny.org/",
+  "image": "http://manu.sporny.org/images/manu.png"
+}
+
+ +
Note

Resolution of relative references to context URLs also applies to remote + context documents, as they may themselves contain references to other contexts.

+ +

JSON documents can be interpreted as JSON-LD without having to be modified by + referencing a context via an HTTP Link Header + as described in § 6.1 Interpreting JSON as JSON-LD. It is also + possible to apply a custom context using the JSON-LD 1.1 API [JSON-LD11-API].

+ +

In JSON-LD documents, + contexts may also be specified inline. + This has the advantage that documents can be processed even in the + absence of a connection to the Web. Ultimately, this is a modeling decision + and different use cases may require different handling. + See Security Considerations in § C. IANA Considerations + for a discussion on using remote contexts.

+ + + +

This section only covers the most basic features of the JSON-LD Context. + The Context can also be used to help interpret other more + complex JSON data structures, such as indexed values, + ordered values, and + nested properties. + More advanced features related to the JSON-LD Context are covered in + § 4. Advanced Concepts.

+
+ +
+

3.2 IRIs

This section is non-normative.

+ +

IRIs (Internationalized Resource Identifiers + [RFC3987]) are fundamental to Linked Data as that is how most + nodes and properties + are identified. + In JSON-LD, IRIs may be represented as an IRI reference. + An IRI is defined in [RFC3987] as containing a + scheme along with path and optional query and + fragment segments. A relative IRI reference is an IRI + that is relative to some other IRI. + In JSON-LD, with exceptions that are as described below, all relative IRI references + are resolved relative to the base IRI.

+ +
Note

As noted in § 1.1 How to Read this Document, + IRIs can often be confused with URLs (Uniform Resource Locators), + the primary distinction is that a URL locates a resource on the web, + an IRI identifies a resource. While it is a good practice for resource identifiers + to be dereferenceable, sometimes this is not practical. In particular, note the + [URN] scheme for Uniform Resource Names, such as UUID. + An example UUID is urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6.

+ +
Note

Properties, values of @type, + and values of properties with a term definition + that defines them as being relative to the vocabulary mapping, + may have the form of a relative IRI reference, but are resolved using the + vocabulary mapping, and not the base IRI.

+ +

A string is interpreted as an IRI when it is the + value of a map entry with the key @id:

+ +
+
+ Example 8: Values of @id are interpreted as IRI + 
{
+  ...
+  "homepage": { "@id": "http://example.com/" }
+  ...
+}
+
+ +

Values that are interpreted as IRIs, can also be + expressed as relative IRI references. For example, + assuming that the following document is located at + http://example.com/about/, the relative IRI reference + ../ would expand to http://example.com/ (for more + information on where relative IRI references can be + used, please refer to section § 9. JSON-LD Grammar).

+ +
+
+ Example 9: IRIs can be relative + 
{
+  ...
+  "homepage": { "@id": "../" }
+  ...
+}
+
+ +

IRIs can be expressed directly in the key position like so:

+ +
+
+ Example 10: IRI as a key + 
{
+  ...
+  "http://schema.org/name": "Manu Sporny",
+  ...
+}
+
+ +

In the example above, the key http://schema.org/name + is interpreted as an IRI.

+ +

Term-to-IRI expansion occurs if the key matches a term defined + within the active context:

+ + + +

JSON keys that do not expand to an IRI, such as status + in the example above, are not Linked Data and thus ignored when processed.

+ +

If type coercion rules are specified in the @context for + a particular term or property IRI, an IRI is generated:

+ + + +

In the example above, since the value http://manu.sporny.org/ + is expressed as a JSON string, the type coercion + rules will transform the value into an IRI when processing the data. + See § 4.2.3 Type Coercion for more + details about this feature.

+ +

In summary, IRIs can be expressed in a variety of + different ways in JSON-LD:

+ +
    +
  1. Map entries that have a key mapping to a term in + the active context expand to an IRI + (only applies outside of the context definition).
    2. +
  2. An IRI is generated for the string value specified using + @id or @type.
    3. +
  3. An IRI is generated for the string value of any key for which there + are coercion rules that contain an @type key that is + set to a value of @id or @vocab.
    4. +
+ +

This section only covers the most basic features associated with IRIs + in JSON-LD. More advanced features related to IRIs are covered in + section § 4. Advanced Concepts. +

+ +
+ +
+

3.3 Node Identifiers

This section is non-normative.

+ +

To be able to externally reference nodes + in an RDF graph, it is important that + nodes have an identifier. IRIs + are a fundamental concept of Linked Data, for + nodes to be truly linked, dereferencing the + identifier should result in a representation of that node. + This may allow an application to retrieve further information about a + node.

+ +

In JSON-LD, a node is identified using the @id + keyword:

+ + + +

The example above contains a node object identified by the IRI + http://me.markus-lanthaler.com/.

+ +

This section only covers the most basic features associated with + node identifiers in JSON-LD. More advanced features related to + node identifiers are covered in section § 4. Advanced Concepts. +

+ +
+ +
+

3.4 Uses of JSON Objects

This section is non-normative.

+

As a syntax, JSON has only a limited number of syntactic elements:

+
    +
  • Numbers, which describe literal numeric values,
    • +
  • Strings, which may describe literal string values, or be used as the keys in a JSON object.
    • +
  • Boolean true and false, which describe literal boolean values,
    • +
  • null, which describes the absence of a value,
    • +
  • Arrays, which describe an ordered set of values of any type, and
    • +
  • JSON objects, which provide a set of map entries, relating keys with values.
    • +
+ +

The JSON-LD data model allows for a richer set of resources, based on the RDF data model. + The data model is described more fully in § 8. Data Model. + JSON-LD uses JSON objects to describe various resources, along with the relationships + between these resources:

+
+
Node objects
+ Node objects are used to define nodes in the linked data graph + which may have both incoming and outgoing edges. + Node objects are principle structure for defining resources having properties. + See § 9.2 Node Objects for the normative definition. +
+
Value objects
+ Value objects are used for describing literal nodes in a linked data graph + which may have only incoming edges. + In JSON, some literal nodes may be described without the use of a JSON object + (e.g., numbers, strings, and boolean values), + but in the expanded form, + all literal nodes are described using value objects. + See § 4.2 Describing Values for more information, + and § 9.5 Value Objects for the normative definition. +
+
List Objects and Set objects
+ List Objects are a special kind of JSON-LD maps, + distinct from node objects and value objects, + used to express ordered values by wrapping an array in a map under the key @list. + Set Objects exist for uniformity, and are equivalent to the array value of the @set key. + See § 4.3.1 Lists and § 4.3.2 Sets + for more detail. +
+
Map Objects
+ JSON-LD uses various forms of maps as ways to more easily access values of a property. +
+
Language Maps
+ Allows multiple values differing in their associated language to be + indexed by language tag. + See § 4.6.2 Language Indexing for more information, + and § 9.8 Language Maps for the normative definition. +
+
Index Maps
+ Allows multiple values (node objects or value objects) to be indexed by an associated @index. + See § 4.6.1 Data Indexing for more information, + and § 9.9 Index Maps for the normative definition. +
+
Id Maps
+ Allows multiple node objects to be indexed by an associated @id. + See § 4.6.3 Node Identifier Indexing for more information, + and § 9.11 Id Maps for the normative definition. +
+
Type Maps
+ Allows multiple node objects to be indexed by an associated @type. + See § 4.6.4 Node Type Indexing for more information, + and § 9.12 Type Maps for the normative definition. +
+
Named Graph Indexing
+ Allows multiple named graphs to be indexed by an associated graph name. + See § 4.9.3 Named Graph Indexing for more information. +
+
+
+
Graph objects
+ A graph object is much like a node object, except that it defines a named graph. + See § 4.9 Named Graphs for more information, + and § 9.4 Graph Objects for the normative definition. + A node object may also describe a named graph, in addition to other properties + defined on the node. The notable difference is that a graph object only describes + a named graph. +
+
Context Definitions
+ A Context Definition uses the JSON object form, but is not itself data in a linked data graph. + A Context Definition also may contain expanded term definitions, + which are also represented using JSON objects. + See § 3.1 The Context, + § 4.1 Advanced Context Usage for more information, + and § 9.15 Context Definitions for the normative definition. +
+
+
+ +
+

3.5 Specifying the Type

This section is non-normative.

+ +

In Linked Data, it is common to specify the type of a graph node; + in many cases, this can be inferred based on the properties used within a + given node object, or the property for which a node is a value. For + example, in the schema.org vocabulary, the givenName + property is associated with a Person. Therefore, one may reason that + if a node object contains the property givenName, that the + type is a Person; making this explicit with @type helps + to clarify the association.

+ +

The type of a particular node can be specified using the @type + keyword. In Linked Data, types are uniquely + identified with an IRI.

+ + + +

A node can be assigned more than one type by using an array:

+ + + +

The value of a @type key may also be a term defined in the active context:

+ + + +

In addition to setting the type of nodes, + @type can also be used to set the type of a value + to create a typed value. + This use of @type is similar to that used to define the type of a node object, + but value objects are restricted to having just a single type. + The use of @type to create typed values is discussed more fully in § 4.2.1 Typed Values.

+ +

Typed values can also be defined implicitly, by specifying + @type in an expanded term definition. + This is covered more fully in § 4.2.3 Type Coercion.

+
+
+ +
+

4. Advanced Concepts

This section is non-normative.

+ +

JSON-LD has a number of features that provide functionality above and beyond + the core functionality described above. JSON can be used to express data + using such structures, and the features described in this + section can be used to interpret a variety of different JSON structures as + Linked Data. A JSON-LD processor will make use of provided and embedded + contexts to interpret property values in a number of different idiomatic + ways.

+ +
+
Describing values
+

One pattern in JSON is for the value of a property to be a string. + Often times, this string actually represents some other typed value, for + example an IRI, a date, or a string in some specific language. See § 4.2 Describing Values for details on how to + describe such value typing.

+
Value ordering
+

In JSON, a property with an array value implies an implicit order; + arrays in JSON-LD do not convey any ordering of the contained elements by + default, unless defined using embedded structures or through a context + definition. See § 4.3 Value Ordering for a + further discussion.

+
Property nesting
+

Another JSON idiom often found in APIs is to use an + intermediate object to group together related properties of an object; in JSON-LD + these are referred to as nested properties and are described in § 4.4 Nested Properties.

+
Referencing objects
+
+

Linked Data is all about describing the relationships between different resources. + Sometimes these relationships are between resources defined in different + documents described on the web, sometimes the resources are described + within the same document.

+ + + +

In this case, a document residing at http://manu.sporny.org/about + may contain the example above, and reference another document at + https://greggkellogg.net/foaf which could include a similar + representation.

+ +

A common idiom found in JSON usage is objects being specified as the + value of other objects, called object embedding in JSON-LD; + for example, a friend specified as an + object value of a Person:

+ + + +

See § 4.5 Embedding details these relationships.

+
+
Indexed values
+

Another common idiom in JSON is to use an intermediate object to represent property values via indexing. JSON-LD allows data to be indexed + in a number of different ways, as detailed in § 4.6 Indexed Values.

+
Reverse Properties
+

JSON-LD serializes directed graphs. That means that + every property points from a node to another node + or value. However, in some cases, it is desirable + to serialize in the reverse direction, as detailed in § 4.8 Reverse Properties.

+
+ +

The following sections describe such + advanced functionality in more detail.

+ +

4.1 Advanced Context Usage

This section is non-normative.

+ +

Section § 3.1 The Context introduced the basics of what makes + JSON-LD work. This section expands on the basic principles of the + context and demonstrates how more advanced use cases can + be achieved using JSON-LD.

+ +

In general, contexts may be used any time a + map is defined. + The only time that one cannot express a context is as a direct child of another context definition (other than as part of an expanded term definition). + For example, a JSON-LD document may + have the form of an array composed of one or more node objects, + which use a context definition in each top-level node object:

+ + + +

The outer array is standard for a document in + expanded document form + and flattened document form, + and may be necessary when describing a disconnected graph, + where nodes may not reference each other. In such cases, using + a top-level map with a @graph property can be useful for saving + the repetition of @context. See § 4.5 Embedding + for more.

+ + + +

Duplicate context terms are overridden using a + most-recently-defined-wins mechanism.

+ + + +

In the example above, the name term is overridden + in the more deeply nested details structure, + which uses its own embedded context. + Note that this is + rarely a good authoring practice and is typically used when working with + legacy applications that depend on a specific structure of the + map. If a term is redefined within a + context, all previous rules associated with the previous definition are + removed. If a term is redefined to null, + the term is effectively removed from the list of + terms defined in the active context.

+ +

Multiple contexts may be combined using an array, which is processed + in order. The set of contexts defined within a specific map are + referred to as local contexts. The + active context refers to the accumulation of + local contexts that are in scope at a + specific point within the document. Setting a local context + to null effectively resets the active context + to an empty context, without term definitions, default language, + or other things defined within previous contexts. + The following example specifies an external context + and then layers an embedded context on top of the external context:

+ +

In JSON-LD 1.1, there are other mechanisms for introducing contexts, including + scoped contexts and imported contexts, and there are new ways of protecting term definitions, + so there are cases where the last defined inline context is not necessarily one + which defines the scope of terms. + See § 4.1.8 Scoped Contexts, + § 4.1.9 Context Propagation, + § 4.1.10 Imported Contexts, and + § 4.1.11 Protected Term Definitions + for further information.

+ + + +
Note

When possible, the context definition should be put + at the top of a JSON-LD document. This makes the document easier to read and + might make streaming parsers more efficient. Documents that do not have the + context at the top are still conformant JSON-LD.

+ +
Note

To avoid forward-compatibility issues, terms + starting with an @ character + followed exclusively by one or more ALPHA characters (see [RFC5234]) + are to be avoided as they + might be used as keyword in future versions + of JSON-LD. Terms starting with an @ character that are not + JSON-LD 1.1 keywords are treated as any other term, i.e., + they are ignored unless mapped to an IRI. Furthermore, the use of + empty terms ("") is not allowed as + not all programming languages are able to handle empty JSON keys.

+ +

4.1.1 JSON-LD 1.1 Processing Mode

This section is non-normative.

+ +

New features defined in JSON-LD 1.1 are available + unless the processing mode is set to json-ld-1.0. + This may be set through an API option. + The processing mode may be explicitly set to json-ld-1.1 using the @version entry in a context + set to the value 1.1 as a number, or through an API option. + Explicitly setting the processing mode to json-ld-1.1 + will prohibit JSON-LD 1.0 processors from incorrectly processing a JSON-LD 1.1 document.

+ +
+
+ Example 23: Setting @version in context + 
{
+  "@context": {
+    "@version": 1.1,
+    ...
+  },
+  ...
+}
+
+ +

The first context encountered when processing a + document which contains @version determines the processing mode, + unless it is defined explicitly through an API option. + This means that if "@version": 1.1 is encountered after processing a context + without @version, + the former will be interpreted as having had "@version": 1.1 defined within it.

+ +
Note

Setting the processing mode explicitly + to json-ld-1.1 is RECOMMENDED to prevent a JSON-LD 1.0 processor + from incorrectly processing a JSON-LD 1.1 document and + producing different results.

+
+ +

4.1.2 Default Vocabulary

This section is non-normative.

+ +

At times, all properties and types may come from the same vocabulary. JSON-LD's + @vocab keyword allows an author to set a common prefix which + is used as the vocabulary mapping and is used + for all properties and types that do not match a term and are neither + an IRI nor a compact IRI (i.e., they do + not contain a colon).

+ + + +

If @vocab is used but certain keys in an + map should not be expanded using + the vocabulary IRI, a term can be explicitly set + to null in the context. For instance, in the + example below the databaseId entry would not expand to an + IRI causing the property to be dropped when expanding.

+ + + +

Since JSON-LD 1.1, + the vocabulary mapping in a local context can be set to a relative IRI reference, + which is concatenated to any vocabulary mapping in the active context + (see § 4.1.4 Using the Document Base for the Default Vocabulary + for how this applies if there is no vocabulary mapping in the active context).

+ +

The following example illustrates the affect of expanding a property using + a relative IRI reference, which is shown in the Expanded (Result) tab below.

+ + + +
Note

The grammar for @vocab, as defined in § 9.15 Context Definitions + allows the value to be a term or compact IRI. + Note that terms used in the value of @vocab must be in scope at the time the context is introduced, + otherwise there would be a circular dependency between @vocab and other terms defined in the same context.

+
+ +

4.1.3 Base IRI

This section is non-normative.

+ +

JSON-LD allows IRIs + to be specified in a relative form which is + resolved against the document base according + section 5.1 Establishing a Base URI + of [RFC3986]. The base IRI may be explicitly set with a context + using the @base keyword.

+ +

For example, if a JSON-LD document was retrieved from http://example.com/document.jsonld, + relative IRI references would resolve against that IRI:

+ +
+
+ Example 27: Use a relative IRI reference as node identifier + 
{
+  "@context": {
+    "label": "http://www.w3.org/2000/01/rdf-schema#label"
+  },
+  "@id": "",
+  "label": "Just a simple document"
+}
+
+ +

This document uses an empty @id, which resolves to the document base. + However, if the document is moved to a different location, the IRI would change. + To prevent this without having to use an IRI, a context + may define an @base mapping, to overwrite the base IRI for the document.

+ + + +

Setting @base to null will prevent + relative IRI references from being expanded to + IRIs.

+ +

Please note that the @base will be ignored if used in + external contexts.

+
+ +
+

4.1.4 Using the Document Base for the Default Vocabulary

This section is non-normative.

+

In some cases, vocabulary terms are defined directly within the document + itself, rather than in an external vocabulary. + Since JSON-LD 1.1, the vocabulary mapping in a local context + can be set to a relative IRI reference, + which is, if there is no vocabulary mapping in scope, resolved against the base IRI. + This causes terms which are expanded relative to the vocabulary, + such as the keys of node objects, + to be based on the base IRI to create IRIs.

+ +
+
+ Example 29: Using "#" as the vocabulary mapping + 
{
+  "@context": {
+    "@version": 1.1,
+    "@base": "http://example/document",
+    "@vocab": "#"
+  },
+  "@id": "http://example.org/places#BrewEats",
+  "@type": "Restaurant",
+  "name": "Brew Eats"
+  ...
+}
+
+ +

If this document were located at http://example/document, it would expand as follows:

+ + +
+ +

4.1.5 Compact IRIs

This section is non-normative.

+ +

A compact IRI is a way of expressing an IRI + using a prefix and suffix separated by a colon (:). + The prefix is a term taken from the + active context and is a short string identifying a + particular IRI in a JSON-LD document. For example, the + prefix foaf may be used as a shorthand for the + Friend-of-a-Friend vocabulary, which is identified using the IRI + http://xmlns.com/foaf/0.1/. A developer may append + any of the FOAF vocabulary terms to the end of the prefix to specify a short-hand + version of the IRI for the vocabulary term. For example, + foaf:name would be expanded to the IRI + http://xmlns.com/foaf/0.1/name.

+ + + +

In the example above, foaf:name expands to the IRI + http://xmlns.com/foaf/0.1/name and foaf:Person expands + to http://xmlns.com/foaf/0.1/Person.

+ +

Prefixes are expanded when the form of the value + is a compact IRI represented as a prefix:suffix + combination, the prefix matches a term defined within the + active context, and the suffix does not begin with two + slashes (//). The compact IRI is expanded by + concatenating the IRI mapped to the prefix to the (possibly empty) + suffix. If the prefix is not defined in the active context, + or the suffix begins with two slashes (such as in http://example.com), + the value is interpreted as IRI instead. If the prefix is an + underscore (_), the value is interpreted as blank node identifier + instead.

+ +

It's also possible to use compact IRIs within the context as shown in the + following example:

+ + + +

When operating explicitly with the processing mode + for JSON-LD 1.0 compatibility, terms may be chosen as compact IRI prefixes when + compacting only if a simple term definition is used where the value ends with a + URI gen-delim character (e.g, /, + # and others, see [RFC3986]).

+ +

In JSON-LD 1.1, terms may be chosen as compact IRI prefixes + when expanding or compacting only if + a simple term definition is used where the value ends with a URI gen-delim character, + or if their expanded term definition contains + a @prefix entry with the value true. + If a simple term definition does not end with a URI gen-delim character, + or a expanded term definition contains + a @prefix entry with the value false, + the term will not be used for either expanding compact IRIs or compacting IRIs to compact IRIs.

+ +
Note

The term selection behavior for 1.0 processors was changed + as a result of an errata against JSON-LD 1.0 reported here. + This does not affect the behavior of processing existing JSON-LD documents, but creates + a slight change when compacting documents using Compact IRIs.

+ +

The behavior when compacting can be illustrated by considering the following input + document in expanded form:

+ +
+
+ Example 33: Expanded document used to illustrate compact IRI creation + 
[{
+  "http://example.com/vocab/property": [{"@value": "property"}],
+  "http://example.com/vocab/propertyOne": [{"@value": "propertyOne"}]
+}]
+
+ +

Using the following context in the 1.0 processing mode + will now select the term vocab rather than + property, even though the IRI associated with + property captures more of the original IRI.

+ +
+
+ Example 34: Compact IRI generation context (1.0) + 
{
+  "@context": {
+    "vocab": "http://example.com/vocab/",
+    "property": "http://example.com/vocab/property"
+  }
+}
+
+ +

Compacting using the previous context with the above expanded input document + results in the following compacted result:

+ + + +

In the original [JSON-LD10], + the term selection algorithm would have selected property, + creating the Compact IRI property:One. + The original behavior can be made explicit using @prefix:

+ +
+
+ Example 36: Compact IRI generation context (1.1) + 
{
+  "@context": {
+    "@version": 1.1,
+    "vocab": "http://example.com/vocab/",
+    "property": {
+      "@id": "http://example.com/vocab/property",
+      "@prefix": true
+    }
+  }
+}
+
+ + + +

In this case, the property term would not normally be usable as a prefix, both + because it is defined with an expanded term definition, and because + its @id does not end in a + gen-delim character. Adding + "@prefix": true allows it to be used as the prefix portion of + the compact IRI property:One.

+
+ +

4.1.6 Aliasing Keywords

This section is non-normative.

+

Each of the JSON-LD keywords, + except for @context, may be aliased to application-specific + keywords. This feature allows legacy JSON content to be utilized + by JSON-LD by re-using JSON keys that already exist in legacy documents. + This feature also allows developers to design domain-specific implementations + using only the JSON-LD context.

+ + + +

In the example above, the @id and @type + keywords have been given the aliases + url and a, respectively.

+ +

Other than for @type, properties of + expanded term definitions where the term is a keyword + result in an error. + Unless the processing mode is set to json-ld-1.0, + there is also an exception for @type; + see § 4.3.3 Using @set with @type for further details + and usage examples.

+ +

Unless the processing mode is set to json-ld-1.0, + aliases of keywords are either simple term definitions, + where the value is a keyword, + or a expanded term definitions with an @id entry and optionally an @protected entry; + no other entries are allowed. + There is also an exception for aliases of @type, + as indicated above. + See § 4.1.11 Protected Term Definitions for further details + of using @protected.

+ +

Since keywords cannot be redefined, they can also not be aliased to + other keywords.

+ +
Note

Aliased keywords may not be used within a context, itself.

+ +

See § 9.16 Keywords for a normative + definition of all keywords.

+
+ +

4.1.7 IRI Expansion within a Context

This section is non-normative.

+

In general, normal IRI expansion rules apply + anywhere an IRI is expected (see § 3.2 IRIs). Within + a context definition, this can mean that terms defined + within the context may also be used within that context as long as + there are no circular dependencies. For example, it is common to use + the xsd namespace when defining typed values:

+ +
+
+ Example 39: IRI expansion within a context + 
{
+  "@context": {
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "age": {
+      "@id": "http://xmlns.com/foaf/0.1/age",
+      "@type": "xsd:integer"
+    },
+    "homepage": {
+      "@id": "http://xmlns.com/foaf/0.1/homepage",
+      "@type": "@id"
+    }
+  },
+  ...
+}
+
+ +

In this example, the xsd term is defined + and used as a prefix for the @type coercion + of the age property.

+ +

Terms may also be used when defining the IRI of another +term:

+ +
+
+ Example 40: Using a term to define the IRI of another term within a context + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "name": "foaf:name",
+    "age": {
+      "@id": "foaf:age",
+      "@type": "xsd:integer"
+    },
+    "homepage": {
+      "@id": "foaf:homepage",
+      "@type": "@id"
+    }
+  },
+  ...
+}
+
+ +

Compact IRIs + and IRIs may be used on the left-hand side of a + term definition.

+ +
+
+ Example 41: Using a compact IRI as a term + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "name": "foaf:name",
+    "foaf:age": {
+      "@id": "http://xmlns.com/foaf/0.1/age",
+      "@type": "xsd:integer"
+    },
+    "foaf:homepage": {
+      "@type": "@id"
+    }
+  },
+  ...
+}
+
+ +

+In this example, the compact IRI form is used in two different ways. + In the first approach, foaf:age declares both the + IRI for the term (using short-form) as well as the + @type associated with the term. In the second + approach, only the @type associated with the term is + specified. The full IRI for + foaf:homepage is determined by looking up the foaf + prefix in the + context.

+ +
Warning

If a compact IRI is used as a term, it must expand to the + value that compact IRI would have on its own when expanded. + This represents a change to the original 1.0 algorithm to prevent terms from + expanding to a different IRI, which could lead to undesired results.

+ +
+
+ Example 42: Illegal Aliasing of a compact IRI to a different IRI + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "name": "foaf:name",
+    "foaf:age": {
+      "@id": "http://xmlns.com/foaf/0.1/age",
+      "@type": "xsd:integer"
+    },
+    "foaf:homepage": {
+     "@id": "http://schema.org/url",
+     "@type": "@id"
+    }
+  },
+  ...
+}
+
+ +

IRIs may also be used in the key position in a context:

+ +
+
+ Example 43: Associating context definitions with IRIs + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/",
+    "xsd": "http://www.w3.org/2001/XMLSchema#",
+    "name": "foaf:name",
+    "foaf:age": {
+      "@id": "http://xmlns.com/foaf/0.1/age",
+      "@type": "xsd:integer"
+    },
+    "http://xmlns.com/foaf/0.1/homepage": {
+      "@type": "@id"
+    }
+  },
+  ...
+}
+
+ +

In order for the IRI to match above, the IRI + needs to be used in the JSON-LD document. Also note that foaf:homepage + will not use the { "@type": "@id" } declaration because + foaf:homepage is not the same as http://xmlns.com/foaf/0.1/homepage. + That is, terms are looked up in a context using + direct string comparison before the prefix lookup mechanism is applied.

+ +
Warning

Neither an IRI reference nor a compact IRI + may expand to some other unrelated IRI. + This represents a change to the original 1.0 algorithm which allowed this behavior but discouraged it.

+ +

The only other exception for using terms in the context is that + circular definitions are not allowed. That is, + a definition of term1 cannot depend on the + definition of term2 if term2 also depends on + term1. For example, the following context definition + is illegal:

+
+
+ Example 44: Illegal circular definition of terms within a context + 
{
+  "@context": {
+    "term1": "term2:foo",
+    "term2": "term1:bar"
+  },
+  ...
+}
+
+
+ +

4.1.8 Scoped Contexts

This section is non-normative.

+ +

An expanded term definition can include a @context + property, which defines a context (a scoped context) for + values of properties defined using that term. + When used for a property, this is called a property-scoped context. + This allows values to use term definitions, the base IRI, + vocabulary mappings or the default language which are different from the + node object they are contained in, as if the + context was specified within the value itself.

+ + + +

In this case, the social profile is defined using the schema.org vocabulary, + but interest is imported from FOAF, + and is used to define a node describing one of Manu's interests + where those properties now come from the FOAF vocabulary.

+ +

Expanding this document, uses a combination of terms defined in the outer context, + and those defined specifically for that term in a property-scoped context.

+ +

Scoping can also be performed using a term used as a value of @type:

+ + + +

Scoping on @type is useful when common properties are used to + relate things of different types, where the vocabularies in use within + different entities calls for different context scoping. For example, + hasPart/partOf may be common terms used in a document, but mean + different things depending on the context. + A type-scoped context is only in effect for the node object on which + the type is used; the previous in-scope contexts are placed back into + effect when traversing into another node object. + As described further in § 4.1.9 Context Propagation, + this may be controlled using the @propagate keyword.

+ +
Note

Any property-scoped or local contexts that were introduced in the node object + would still be in effect when traversing into another node object.

+ +

When expanding, each value of @type is considered + (ordering them lexicographically) where that value is also a term in + the active context having its own type-scoped context. + If so, that the scoped context is applied to the active context.

+ +
Note

The values of @type are unordered, so if multiple + types are listed, the order that type-scoped contexts are applied is based on + lexicographical ordering.

+ +

For example, consider the following semantically equivalent examples. + The first example, shows how properties and types can define their own + scoped contexts, which are included when expanding.

+ +
+
+ Example 47: Expansion using embedded and scoped contexts + 
{
+  "@context": {
+    "@version": 1.1,
+    "@vocab": "http://example.com/vocab/",
+    "property": {
+      "@id": "http://example.com/vocab/property",
+      "@context": {
+        "term1": "http://example.com/vocab/term1"
+         ↑ Scoped context for "property" defines term1
+      }
+    },
+    "Type1": {
+      "@id": "http://example.com/vocab/Type1",
+      "@context": {
+        "term3": "http://example.com/vocab/term3"
+         ↑ Scoped context for "Type1" defines term3
+      }
+    },
+    "Type2": {
+      "@id": "http://example.com/vocab/Type2",
+      "@context": {
+        "term4": "http://example.com/vocab/term4"
+         ↑ Scoped context for "Type2" defines term4
+      }
+    }
+  },
+  "property": {
+    "@context": {
+      "term2": "http://example.com/vocab/term2"
+         ↑ Embedded context defines term2
+    },
+    "@type": ["Type2", "Type1"],
+    "term1": "a",
+    "term2": "b",
+    "term3": "c",
+    "term4": "d"
+  }
+}
+
+ +

Contexts are processed depending on how they are defined. + A property-scoped context is processed first, + followed by any embedded context, + followed lastly by the type-scoped contexts, + in the appropriate order. The previous example is logically equivalent to the following:

+ +
+
+ Example 48: Expansion using embedded and scoped contexts (embedding equivalent) + 
{
+  "@context": {
+    "@vocab": "http://example.com/vocab/",
+    "property": "http://example.com/vocab/property",
+    "Type1": "http://example.com/vocab/Type1",
+    "Type2": "http://example.com/vocab/Type2"
+  },
+  "property": {
+    "@context": [{
+        "term1": "http://example.com/vocab/term1"
+         ↑ Previously scoped context for "property" defines term1
+      }, {
+        "term2": "http://example.com/vocab/term2"
+         ↑ Embedded context defines term2
+      }, {
+        "term3": "http://example.com/vocab/term3"
+         ↑ Previously scoped context for "Type1" defines term3
+      }, {
+      "term4": "http://example.com/vocab/term4"
+         ↑ Previously scoped context for "Type2" defines term4
+    }],
+    "@type": ["Type2", "Type1"],
+    "term1": "a",
+    "term2": "b",
+    "term3": "c",
+    "term4": "d"
+  }
+}
+
+ +
Note

If a term defines a scoped context, + and then that term is later redefined, + the association of the context defined in the earlier + expanded term definition is lost + within the scope of that redefinition. This is consistent with + term definitions of a term overriding previous term definitions from + earlier less deeply nested definitions, as discussed in + § 4.1 Advanced Context Usage.

+ +
Note

Scoped Contexts are a new feature in JSON-LD 1.1.

+
+ +

4.1.9 Context Propagation

This section is non-normative.

+

Once introduced, contexts remain in effect until a subsequent + context removes it by setting @context to null, + or by redefining terms, + with the exception of type-scoped contexts, + which limit the effect of that context until the next node object is entered. + This behavior can be changed using the @propagate keyword.

+ +

The following example illustrates how terms defined in a context with @propagate set to false + are effectively removed when descending into new node object.

+ + + +
Note

Contexts included within an array must all have the same value for @propagate + due to the way that rollback is defined in JSON-LD 1.1 Processing Algorithms and API.

+
+ +

4.1.10 Imported Contexts

This section is non-normative.

+

JSON-LD 1.0 included mechanisms for modifying the context that + is in effect. This included the capability to load and process a remote + context and then apply further changes to it via new contexts. +

+ +

However, with the introduction of JSON-LD 1.1, it is also desirable to + be able to load a remote context, in particular an existing JSON-LD + 1.0 context, and apply JSON-LD 1.1 features to it prior to + processing.

+ +

By using the @import keyword in a context, another remote + context, referred to as an imported context, can be loaded and + modified prior to processing. The modifications are expressed in the + context that includes the @import keyword, referred to as the + wrapping context. Once an imported context is loaded, the + contents of the wrapping context are merged into it prior to + processing. The merge operation will cause each key-value pair in the + wrapping context to be added to the loaded imported context, + with the wrapping context key-value pairs taking precedence.

+ +

By enabling existing contexts to be reused and edited inline prior + to processing, context-wide keywords can be applied to adjust all term + definitions in the imported context. Similarly, term definitions can + be replaced prior to processing, enabling adjustments that, for instance, ensure term + definitions match previously protected terms or that they include + additional type coercion information.

+ +

The following examples illustrate how @import can be used to express + a type-scoped context that loads an imported context and + sets @propagate to true, as a technique for making other similar modifications.

+ +

Suppose there was a context that could be referenced remotely + via the URL https://json-ld.org/contexts/remote-context.jsonld:

+ +
+
+ Example 50: A remote context to be imported in a type-scoped context + 
{
+  "@context": {
+    "Type1": "http://example.com/vocab/Type1",
+    "Type2": "http://example.com/vocab/Type2",
+    "term1": "http://example.com/vocab#term1",
+    "term2": "http://example.com/vocab#term2",
+    ...
+  }
+}
+
+ +

A wrapping context could be used to source it and modify it:

+ +
+
+ Example 51: Sourcing a context in a type-scoped context and setting it to propagate + 
{
+  "@context": {
+    "@version": 1.1,
+    "MyType": {
+      "@id": "http://example.com/vocab#MyType",
+      "@context": {
+        "@version": 1.1,
+        "@import": "https://json-ld.org/contexts/remote-context.jsonld",
+        "@propagate": true
+      }
+    }
+  }
+}
+
+ +

The effect would be the same as if the entire imported context + had been copied into the type-scoped context:

+ +
+
+ Example 52: Result of sourcing a context in a type-scoped context and setting it to propagate + 
{
+  "@context": {
+    "@version": 1.1,
+    "MyType": {
+      "@id": "http://example.com/vocab#MyType",
+      "@context": {
+        "@version": 1.1,
+        "Type1": "http://example.com/vocab/Type1",
+        "Type2": "http://example.com/vocab/Type2",
+        "term1": "http://example.com/vocab#term1",
+        "term2": "http://example.com/vocab#term2",
+        ...
+        "@propagate": true
+      }
+    }
+  }
+}
+
+ +

Similarly, the wrapping context may replace term definitions or + set other context-wide keywords that may affect how the imported + context term definitions will be processed:

+ +
+
+ Example 53: Sourcing a context to modify @vocab and a term definition + 
{
+  "@context": {
+    "@version": 1.1,
+    "@import": "https://json-ld.org/contexts/remote-context.jsonld",
+    "@vocab": "http://example.org/vocab#",
+     ↑ This will replace any previous @vocab definition prior to processing it
+    "term1": {
+      "@id": "http://example.org/vocab#term1",
+      "@type": "http://www.w3.org/2001/XMLSchema#integer"
+    }
+     ↑ This will replace the old term1 definition prior to processing it
+  }
+}
+
+ +

Again, the effect would be the same as if the entire imported context + had been copied into the context:

+ +
+
+ Example 54: Result of sourcing a context to modify @vocab and a term definition + 
{
+  "@context": {
+    "@version": 1.1,
+    "Type1": "http://example.com/vocab/Type1",
+    "Type2": "http://example.com/vocab/Type2",
+    "term1": {
+      "@id": "http://example.org/vocab#term1",
+      "@type": "http://www.w3.org/2001/XMLSchema#integer"
+    },
+     ↑ Note term1 has been replaced prior to processing
+    "term2": "http://example.com/vocab#term2",
+    ...,
+    "@vocab": "http://example.org/vocab#"
+  }
+}
+
+ +

The result of loading imported contexts must be + context definition, not an IRI or an array. + Additionally, the imported context cannot include an @import entry.

+
+ +

4.1.11 Protected Term Definitions

This section is non-normative.

+

JSON-LD is used in many specifications as the specified data format. + However, there is also a desire to allow some JSON-LD contents to be processed as plain JSON, + without using any of the JSON-LD algorithms. + Because JSON-LD is very flexible, + some terms from the original format may be locally overridden + through the use of embedded contexts, + and take a different meaning for JSON-LD based implementations. + On the other hand, "plain JSON" implementations may not be able to interpret these embedded contexts, + and hence will still interpret those terms with their original meaning. + To prevent this divergence of interpretation, + JSON-LD 1.1 allows term definitions to be protected. +

+

A protected term definition is a term definition with an entry @protected set to true. + It generally prevents further contexts from overriding this term definition, + either through a new definition of the same term, + or through clearing the context with "@context": null. + Such attempts will raise an error and abort the processing + (except in some specific situations described + below). +

+ + +
+
+ Example 55: A protected term definition can generally not be overridden + 
{
+  "@context": [
+    {
+      "@version": 1.1,
+      "Person": "http://xmlns.com/foaf/0.1/Person",
+      "knows": "http://xmlns.com/foaf/0.1/knows",
+      "name": {
+        "@id": "http://xmlns.com/foaf/0.1/name",
+        "@protected": true
+      }
+    },
+    {
+      – this attempt will fail with an error
+      "name": "http://schema.org/name"
+    }
+  ],
+  "@type": "Person",
+  "name": "Manu Sporny",
+  "knows": {
+    "@context": [
+      – this attempt would also fail with an error
+      null,
+      "http://schema.org/"
+    ],
+    "name": "Gregg Kellogg"
+  }
+}
+
+ +

When all or most term definitions of a context need to be protected, + it is possible to add an entry @protected set to true + to the context itself. + It has the same effect as protecting each of its term definitions individually. + Exceptions can be made by adding an entry @protected set to false + in some term definitions. +

+ + + +

+ While protected terms can in general not be overridden, + there are two exceptions to this rule. + The first exception is that a context is allowed to redefine a protected term + if the new definition is identical to the protected term definition + (modulo the @protected flag). + The rationale is that the new definition does not violate the protection, + as it does not change the semantics of the protected term. + This is useful for widespread term definitions, + such as aliasing @type to type, + which may occur (including in a protected form) in several contexts. +

+ + + +

The second exception is that a property-scoped context + is not affected by protection, and can therefore override protected terms, + either with a new term definition, + or by clearing the context with "@context": null. +

+

The rationale is that "plain JSON" implementations, + relying on a given specification, + will only traverse properties defined by that specification. + Scoped contexts belonging to the specified properties are part of the specification, + so the "plain JSON" implementations are expected to be aware of the change of semantics they induce. + Scoped contexts belonging to other properties apply to parts of the document that "plain JSON" implementations will ignore. + In both cases, there is therefore no risk of diverging interpretations between JSON-LD-aware implementations and "plain JSON" implementations, + so overriding is permitted. +

+ + +
Note

By preventing terms from being overridden, + protection also prevents any adaptation of a term + (e.g., defining a more precise datatype, restricting the term's use to lists, etc.). + This kind of adaptation is frequent with some general purpose contexts, + for which protection would therefore hinder their usability. + As a consequence, context publishers should use this feature with care. +

+ +
Note

Protected term definitions are a new feature in JSON-LD 1.1.

+
+
+ +

4.2 Describing Values

This section is non-normative.

+

Values are leaf nodes in a graph associated with scalar values such as + strings, dates, times, and other such atomic values.

+ +

4.2.1 Typed Values

This section is non-normative.

+ +

A value with an associated type, also known as a + typed value, is indicated by associating a value with + an IRI which indicates the value's type. Typed values may be + expressed in JSON-LD in three ways:

+ +
    +
  1. By utilizing the @type keyword when defining + a term within an @context section.
    2. +
  2. By utilizing a value object.
    3. +
  3. By using a native JSON type such as number, true, or false.
    4. +
+ +

The first example uses the @type keyword to associate a + type with a particular term in the @context:

+ + + +

The modified key's value above is automatically interpreted as a + dateTime value because of the information specified in the + @context. The example tabs show how a JSON-LD processor will interpret the data.

+ +

The second example uses the expanded form of setting the type information + in the body of a JSON-LD document:

+ + + +

Both examples above would generate the value + 2010-05-29T14:17:39+02:00 with the type + http://www.w3.org/2001/XMLSchema#dateTime. Note that it is + also possible to use a term or a compact IRI to + express the value of a type.

+ +
Note

The @type keyword is also used to associate a type + with a node. + The concept of a node type and a value type are distinct. + For more on adding types to nodes, see § 3.5 Specifying the Type.

+ +
Note

When expanding, an @type defined within a term definition + can be associated with a string value to create an expanded value object, + which is described in § 4.2.3 Type Coercion. + Type coercion only takes place on string values, not for values which are maps, + such as node objects and value objects in their expanded form.

+ +

A node type specifies the type of thing + that is being described, like a person, place, event, or web page. A + value type specifies the data type of a particular value, such + as an integer, a floating point number, or a date.

+ +
+
+ Example 61: Example demonstrating the context-sensitivity for @type + 
{
+  ...
+  "@id": "http://example.org/posts#TripToWestVirginia",
+  "@type": "http://schema.org/BlogPosting",  ← This is a node type
+  "http://purl.org/dc/terms/modified": {
+    "@value": "2010-05-29T14:17:39+02:00",
+    "@type": "http://www.w3.org/2001/XMLSchema#dateTime"  ← This is a value type
+  }
+  ...
+}
+
+ +

The first use of @type associates a node type + (http://schema.org/BlogPosting) with the node, + which is expressed using the @id keyword. + The second use of @type associates a value type + (http://www.w3.org/2001/XMLSchema#dateTime) with the + value expressed using the @value keyword. As a + general rule, when @value and @type are used in + the same map, the @type + keyword is expressing a value type. + Otherwise, the @type keyword is expressing a + node type. The example above expresses the following data:

+ + +
+ +

4.2.2 JSON Literals

This section is non-normative.

+

At times, it is useful to include JSON within JSON-LD that is not interpreted as JSON-LD. + Generally, a JSON-LD processor will ignore properties which don't map to IRIs, + but this causes them to be excluded when performing various algorithmic transformations. + But, when the data that is being described is, itself, JSON, it's important that + it survives algorithmic transformations.

+ +
Warning

JSON-LD is intended to allow native JSON to be + interpreted through the use of a context. + The use of JSON literals creates blobs of data which are not available for interpretation. + It is for use only in the rare cases that JSON cannot be represented as JSON-LD.

+ +

When a term is defined with @type set to @json, + a JSON-LD processor will treat the value as a JSON literal, + rather than interpreting it further as JSON-LD. + In the expanded document form, such JSON will become the value of @value within a value object + having "@type": "@json".

+ +

When transformed into RDF, the JSON literal will have a lexical form based on + a specific serialization of the JSON, + as described in Compaction algorithm of [JSON-LD11-API] + and the JSON datatype.

+ +

The following example shows an example of a JSON Literal contained as the + value of a property. Note that the RDF results use a canonicalized form of the JSON + to ensure interoperability between different processors. + JSON canonicalization is described in Data Round Tripping in [JSON-LD11-API].

+ + + +
Note

Generally, when a JSON-LD processor encounters null, + the associated entry or value is removed. + However, null is a valid JSON token; when used as the value + of a JSON literal, a null value will be preserved.

+
+ +

4.2.3 Type Coercion

This section is non-normative.

+ +

JSON-LD supports the coercion of string values to particular data types. +Type coercion allows someone deploying JSON-LD to use string property values +and have those values be interpreted as typed values +by associating an IRI with the value in the expanded value object representation. +Using type coercion, string value representation can be used without requiring +the data type to be specified explicitly with each piece of data.

+ +

Type coercion is specified within an expanded term definition + using the @type key. The value of this key expands to an IRI. + Alternatively, the keyword @id or @vocab may be used + as value to indicate that within the body of a JSON-LD document, a string value of a + term coerced to @id or @vocab is to be interpreted as an + IRI. The difference between @id and @vocab is how values are expanded + to IRIs. @vocab first tries to expand the value + by interpreting it as term. If no matching term is found in the + active context, it tries to expand it as an IRI or a compact IRI + if there's a colon in the value; otherwise, it will expand the value using the + active context's vocabulary mapping, if present. + Values coerced to @id in contrast are expanded as + an IRI or a compact IRI if a colon is present; otherwise, they are interpreted + as relative IRI references.

+ +
Note

The ability to coerce a value using a term definition is distinct + from setting one or more types on a node object, as the former does not result in + new data being added to the graph, while the latter manages node types + through adding additional relationships to the graph.

+ +

Terms or compact IRIs used as the value of a + @type key may be defined within the same context. This means that one may specify a + term like xsd and then use xsd:integer within the same + context definition.

+ +

The example below demonstrates how a JSON-LD author can coerce values to +typed values and IRIs.

+ + + +

It is important to note that terms are only used in expansion + for vocabulary-relative positions, such as for keys and values of map entries. + Values of @id are considered to be document-relative, + and do not use term definitions for expansion. For example, consider the following:

+ + + +

The unexpected result is that "barney" expands to both http://example1.com/barney + and http://example2.com/barney, depending where it is encountered. + String values interpreted as IRIs because of the associated term definitions + are typically considered to be document-relative. + In some cases, it makes sense to interpret these relative to the vocabulary, + prescribed using "@type": "@vocab" in the term definition, though this can + lead to unexpected consequences such as these.

+ +

In the previous example, "barney" appears twice, once as the value of @id, + which is always interpreted as a document-relative IRI, and once as the value of + "fred", which is defined to be vocabulary-relative, thus the different expanded values.

+ +

For more on this see § 4.1.2 Default Vocabulary.

+ +

A variation on the previous example using "@type": "@id" instead + of @vocab illustrates the behavior of interpreting "barney" relative to the document:

+ + + + +
Note

The triple ex1:fred ex2:knows ex1:barney . is emitted twice, + but exists only once in an output dataset, as it is a duplicate triple.

+ +

Terms may also be defined using IRIs + or compact IRIs. This allows coercion rules + to be applied to keys which are not represented as a simple term. + For example:

+ + + +

In this case the @id definition in the term definition is optional. + If it does exist, the IRI or compact IRI representing + the term will always be expanded to IRI defined by the @id + key—regardless of whether a prefix is defined or not.

+ +

Type coercion is always performed using the unexpanded value of the key. In the + example above, that means that type coercion is done looking for foaf:age + in the active context and not for the corresponding, expanded + IRI http://xmlns.com/foaf/0.1/age.

+ +
Note

Keys in the context are treated as terms for the purpose of + expansion and value coercion. At times, this may result in multiple representations for the same expanded IRI. + For example, one could specify that dog and cat both expanded to http://example.com/vocab#animal. + Doing this could be useful for establishing different type coercion or language specification rules.

+
+ +

4.2.4 String Internationalization

This section is non-normative.

+

At times, it is important to annotate a string + with its language. In JSON-LD this is possible in a variety of ways. + First, it is possible to define a default language for a JSON-LD document + by setting the @language key in the context:

+ + + +

The example above would associate the ja language + tag with the two strings 花澄 and 科学者 + Languages tags are defined in [BCP47]. + The default language applies to all + string values that are not type coerced.

+ +

To clear the default language for a subtree, @language can + be set to null in an intervening context, such as a scoped context as follows:

+ +
+
+ Example 69: Clearing default language + 
{
+  "@context": {
+    ...
+    "@version": 1.1,
+    "@vocab": "http://example.com/",
+    "@language": "ja",
+    "details": {
+      "@context": {
+        "@language": null
+      }
+    }
+  },
+  "name": "花澄",
+  "details": {"occupation": "Ninja"}
+}
+
+ +

Second, it is possible to associate a language with a specific term + using an expanded term definition:

+ +
+
+ Example 70: Expanded term definition with language + 
{
+  "@context": {
+    ...
+    "ex": "http://example.com/vocab/",
+    "@language": "ja",
+    "name": { "@id": "ex:name", "@language": null },
+    "occupation": { "@id": "ex:occupation" },
+    "occupation_en": { "@id": "ex:occupation", "@language": "en" },
+    "occupation_cs": { "@id": "ex:occupation", "@language": "cs" }
+  },
+  "name": "Yagyū Muneyoshi",
+  "occupation": "忍者",
+  "occupation_en": "Ninja",
+  "occupation_cs": "Nindža",
+  ...
+}
+
+ +

The example above would associate 忍者 with the specified default + language tag ja, Ninja with the language tag + en, and Nindža with the language tag cs. + The value of name, Yagyū Muneyoshi wouldn't be + associated with any language tag since @language was reset to + null in the expanded term definition.

+ +
Note

Language associations are only applied to plain + strings. Typed values + or values that are subject to type coercion + are not language tagged.

+ +

Just as in the example above, systems often need to express the value of a + property in multiple languages. Typically, such systems also try to ensure that + developers have a programmatically easy way to navigate the data structures for + the language-specific data. In this case, language maps + may be utilized.

+ +
+
+ Example 71: Language map expressing a property in three languages + 
{
+  "@context": {
+    ...
+    "occupation": { "@id": "ex:occupation", "@container": "@language" }
+  },
+  "name": "Yagyū Muneyoshi",
+  "occupation": {
+    "ja": "忍者",
+    "en": "Ninja",
+    "cs": "Nindža"
+  }
+  ...
+}
+
+ +

The example above expresses exactly the same information as the previous + example but consolidates all values in a single property. To access the + value in a specific language in a programming language supporting dot-notation + accessors for object properties, a developer may use the + property.language pattern + (when languages are limited to the primary language sub-tag, + and do not depend on other sub-tags, such as "en-us"). + For example, to access the occupation + in English, a developer would use the following code snippet: + obj.occupation.en.

+ +

Third, it is possible to override the default language by using a + value object:

+ +
+
+ Example 72: Overriding default language using an expanded value + 
{
+  "@context": {
+    ...
+    "@language": "ja"
+  },
+  "name": "花澄",
+  "occupation": {
+    "@value": "Scientist",
+    "@language": "en"
+  }
+}
+
+ +

This makes it possible to specify a plain string by omitting the + @language tag or setting it to null when expressing + it using a value object:

+ +
+
+ Example 73: Removing language information using an expanded value + 
{
+  "@context": {
+    ...
+    "@language": "ja"
+  },
+  "name": {
+    "@value": "Frank"
+  },
+  "occupation": {
+    "@value": "Ninja",
+    "@language": "en"
+  },
+  "speciality": "手裏剣"
+}
+
+ +

See § 9.8 Language Maps for a description + of using language maps to set the language of mapped values.

+ +
4.2.4.1 Base Direction

This section is non-normative.

+

It is also possible to annotate a string, or language-tagged string, + with its base direction. + As with language, it is possible to define a default base direction for a JSON-LD document + by setting the @direction key in the context:

+ + + +

The example above would associate the ar-EG language tag + and "rtl" base direction + with the two strings + HTML و CSS: تصميم و إنشاء مواقع الويب and مكتبة. + The default base direction applies to all + string values that are not type coerced.

+ +

To clear the default base direction for a subtree, @direction can + be set to null in an intervening context, such as a scoped context as follows:

+ +
+
+ Example 75: Clearing default base direction + 
{
+  "@context": {
+    ...
+    "@version": 1.1,
+    "@vocab": "http://example.com/",
+    "@language": "ar-EG",
+    "@direction": "rtl",
+    "details": {
+      "@context": {
+        "@direction": null
+      }
+    }
+  },
+  "title": "HTML و CSS: تصميم و إنشاء مواقع الويب",
+  "details": {"genre": "Technical Publication"}
+}
+
+ +

Second, it is possible to associate a base direction with a specific term + using an expanded term definition:

+ +
+
+ Example 76: Expanded term definition with language and direction + 
{
+  "@context": {
+    ...
+    "@version": 1.1,
+    "@language": "ar-EG",
+    "@direction": "rtl",
+    "ex": "http://example.com/vocab/",
+    "publisher": { "@id": "ex:publisher", "@direction": null },
+    "title": { "@id": "ex:title" },
+    "title_en": { "@id": "ex:title", "@language": "en", "@direction": "ltr" }
+  },
+  "publisher": "مكتبة",
+  "title": "HTML و CSS: تصميم و إنشاء مواقع الويب",
+  "title_en": "HTML and CSS: Design and Build Websites",
+  ...
+}
+
+ +

The example above would create three properties:

+ + + + + + + +
SubjectPropertyValueLanguageDirection
_:b0http://example.com/vocab/publisherمكتبةar-EG
_:b0http://example.com/vocab/titleHTML و CSS: تصميم و إنشاء مواقع الويبar-EGrtl
_:b0http://example.com/vocab/titleHTML and CSS: Design and Build Websitesenltr
+ +
Note

Base direction associations are only applied to plain + strings and language-tagged strings. + Typed values or values that are subject to type coercion + are not given a base direction.

+ +

Third, it is possible to override the default base direction by using a + value object:

+ +
+
+ Example 77: Overriding default language and default base direction using an expanded value + 
{
+  "@context": {
+    ...
+    "@language": "ar-EG",
+    "@direction": "rtl"
+  },
+  "title": "HTML و CSS: تصميم و إنشاء مواقع الويب",
+  "author": {
+    "@value": "Jon Duckett",
+    "@language": "en",
+    "@direction": null
+  }
+}
+
+ +

See Strings on the Web: Language and Direction Metadata [string-meta] for a deeper discussion of base direction.

+
+
+ +
+ +

4.3 Value Ordering

This section is non-normative.

+ +

A JSON-LD author can express multiple values in a compact way by using + arrays. Since graphs do not describe ordering for links + between nodes, arrays in JSON-LD do not convey any ordering of the + contained elements by default. This is exactly the opposite from regular JSON + arrays, which are ordered by default. For example, consider the following + simple document:

+ + + +

Multiple values may also be expressed using the expanded form:

+ + + +
Note

The example shown above would generates statement, again with + no inherent order.

+ +

Although multiple values of a property are typically of the same type, + JSON-LD places no restriction on this, and a property may have values + of different types:

+ + + +
Note

When viewed as statements, the values have no inherent order.

+ + +

4.3.1 Lists

This section is non-normative.

+

As the notion of ordered collections is rather important in data + modeling, it is useful to have specific language support. In JSON-LD, + a list may be represented using the @list keyword as follows:

+ + + +

This describes the use of this array as being ordered, + and order is maintained when processing a document. If every use of a given multi-valued + property is a list, this may be abbreviated by setting @container + to @list in the context:

+ + + +

The implementation of lists in RDF depends on linking anonymous nodes + together using the properties rdf:first and + rdf:rest, with the end of the list defined as the resource + rdf:nil, as the "statements" tab illustrates. + This allows order to be represented within an unordered set of statements. +

+ +

Both JSON-LD and Turtle provide shortcuts for representing ordered lists.

+ +

In JSON-LD 1.1, lists of lists, where the value of + a list object, may itself be a list object, are + fully supported.

+ +

Note that the "@container": "@list" definition recursively + describes array values of lists as being, themselves, lists. For example, in The GeoJSON Format (see [RFC7946]), + coordinates are an ordered list of positions, which are + represented as an array of two or more numbers:

+ +
+
+ Example 83: Coordinates expressed in GeoJSON + 
{
+  "type": "Feature",
+  "bbox": [-10.0, -10.0, 10.0, 10.0],
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+        [
+            [-10.0, -10.0],
+            [10.0, -10.0],
+            [10.0, 10.0],
+            [-10.0, -10.0]
+        ]
+    ]
+  }
+  //...
+}
+
+ +

For these examples, it's important that values + expressed within bbox and coordinates maintain their order, + which requires the use of embedded list structures. In JSON-LD 1.1, we can + express this using recursive lists, by simply adding the appropriate context + definition:

+ + + +

Note that coordinates includes three levels of lists.

+ +

Values of terms associated with an @list container + are always represented in the form of an array, + even if there is just a single value or no value at all.

+
+ +

4.3.2 Sets

This section is non-normative.

+ +

While @list is used to describe ordered lists, + the @set keyword is used to describe unordered sets. + The use of @set in the body of a JSON-LD document + is optimized away when processing the document, as it is just syntactic + sugar. However, @set is helpful when used within the context + of a document. + Values of terms associated with an @set container + are always represented in the form of an array, + even if there is just a single value that would otherwise be optimized to + a non-array form in compact form (see + § 5.2 Compacted Document Form). This makes post-processing of + JSON-LD documents easier as the data is always in array form, even if the + array only contains a single value.

+ + + +

This describes the use of this array as being unordered, + and order may change when processing a document. By default, + arrays of values are unordered, but this may be made explicit by + setting @container to @set in the context: + +

+ +

Since JSON-LD 1.1, the @set keyword may be + combined with other container specifications within an expanded term + definition to similarly cause compacted values of indexes to be consistently + represented using arrays. See § 4.6 Indexed Values for a further discussion.

+
+ +

4.3.3 Using @set with @type

This section is non-normative.

+

Unless the processing mode is set to json-ld-1.0, + @type may be used with an expanded term definition with @container set + to @set; no other entries may be set within such an expanded term definition. + This is used by the Compaction algorithm to ensure that the values of @type (or an alias) + are always represented in an array.

+ +
+
+ Example 87: Setting @container: @set on @type + 
{
+  "@context": {
+    "@version": 1.1,
+    "@type": {"@container": "@set"}
+  },
+  "@type": ["http:/example.org/type"]
+}
+
+ +
+
+ + +

4.4 Nested Properties

This section is non-normative.

+ +

Many JSON APIs separate properties from their entities using an + intermediate object; in JSON-LD these are called nested properties. + For example, a set of possible labels may be grouped + under a common property:

+ + + +

By defining labels using the keyword @nest, + a JSON-LD processor will ignore the nesting created by using the + labels property and process the contents as if it were declared + directly within containing object. In this case, the labels + property is semantically meaningless. Defining it as equivalent to + @nest causes it to be ignored when expanding, making it + equivalent to the following:

+ + + +

Similarly, term definitions may contain a @nest property + referencing a term aliased to @nest which will cause such + properties to be nested under that aliased term when compacting. + In the example below, both main_label and other_label are defined + with "@nest": "labels", which will cause them to be serialized under + labels when compacting.

+ +
+
+ Example 90: Defining property nesting - Expanded Input + 
[{
+  "@id": "http://example.org/myresource",
+  "http://xmlns.com/foaf/0.1/homepage": [
+    {"@id": "http://example.org"}
+  ],
+  "http://www.w3.org/2004/02/skos/core#prefLabel": [
+    {"@value": "This is the main label for my resource"}
+  ],
+  "http://www.w3.org/2004/02/skos/core#altLabel": [
+    {"@value": "This is the other label"}
+  ]
+}]
+
+ +
+
+ Example 91: Defining property nesting - Context + 
{
+  "@context": {
+    "@version": 1.1,
+    "skos": "http://www.w3.org/2004/02/skos/core#",
+    "labels": "@nest",
+    "main_label": {"@id": "skos:prefLabel", "@nest": "labels"},
+    "other_label": {"@id": "skos:altLabel", "@nest": "labels"},
+    "homepage": {"@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id"}
+  }
+}
+
+ + + +
Note

Nested properties are a new feature in JSON-LD 1.1.

+
+ +

4.5 Embedding

This section is non-normative.

+ +

Embedding is a JSON-LD feature that allows an author to + use node objects as + property values. This is a commonly used mechanism for + creating a parent-child relationship between two nodes.

+ +

Without embedding, node objects can be linked by referencing the + identifier of another node object. For example:

+ + + +

The previous example describes two node objects, for Manu and Gregg, with + the knows property defined to treat string values as identifiers. + Embedding allows the node object for Gregg to be embedded as a value + of the knows property:

+ + + +

A node object, like the one used above, may be used in + any value position in the body of a JSON-LD document.

+ +

While it is considered a best practice to identify nodes in a graph, + at times this is impractical. In the data model, nodes without an explicit + identifier are called blank nodes, which can be represented in a + serialization such as JSON-LD using a blank node identifier. In the + previous example, the top-level node for Manu does not have an identifier, + and does not need one to describe it within the data model. However, if we + were to want to describe a knows relationship from Gregg to Manu, + we would need to introduce a blank node identifier + (here _:b0).

+ + + +

Blank node identifiers may be automatically introduced by algorithms such as flattening, but they are also useful for authors to describe such relationships directly.

+ +

4.5.1 Identifying Blank Nodes

This section is non-normative.

+ +

At times, it becomes necessary to be able to express information without + being able to uniquely identify the node with an IRI. + This type of node is called a blank node. JSON-LD does not require + all nodes to be identified using @id. However, some graph topologies + may require identifiers to be serializable. Graphs containing loops, e.g., cannot + be serialized using embedding alone, @id must be used to connect the nodes. + In these situations, one can use blank node identifiers, + which look like IRIs using an underscore (_) + as scheme. This allows one to reference the node locally within the document, but + makes it impossible to reference the node from an external document. The + blank node identifier is scoped to the document in which it is used.

+ + + +

The example above contains information about two secret agents that cannot be identified + with an IRI. While expressing that agent 1 knows agent 2 + is possible without using blank node identifiers, + it is necessary to assign agent 1 an identifier so that it can be referenced + from agent 2.

+

It is worth noting that blank node identifiers may be relabeled during processing. + If a developer finds that they refer to the blank node more than once, + they should consider naming the node using a dereferenceable IRI so that + it can also be referenced from other documents.

+
+
+ +

4.6 Indexed Values

This section is non-normative.

+ +

Sometimes multiple property values need to be accessed + in a more direct fashion than iterating though multiple array values. JSON-LD + provides an indexing mechanism to allow the use of an intermediate map + to associate specific indexes with associated values.

+ +
+
Data Indexing
As described in § 4.6.1 Data Indexing, + data indexing allows an arbitrary key to reference a node or value.
+
Language Indexing
As described in § 4.6.2 Language Indexing, + language indexing allows a language to reference a string and be + interpreted as the language associated with that string.
+
Node Identifier Indexing
As described in § 4.6.3 Node Identifier Indexing, + node identifier indexing allows an IRI to reference a node + and be interpreted as the identifier of that node.
+
Node Type Indexing
As described in § 4.6.4 Node Type Indexing, + node type indexing allows an IRI to reference a node + and be interpreted as a type of that node.
+
+ +

See § 4.9 Named Graphs for other uses of indexing in JSON-LD.

+ +

4.6.1 Data Indexing

This section is non-normative.

+ +

Databases are typically used to make access to + data more efficient. Developers often extend this sort of functionality into + their application data to deliver similar performance gains. + This data may have no meaning from a Linked Data standpoint, but is + still useful for an application.

+ +

JSON-LD introduces the notion of index maps + that can be used to structure data into a form that is + more efficient to access. The data indexing feature allows an author to + structure data using a simple key-value map where the keys do not map + to IRIs. This enables direct access to data + instead of having to scan an array in search of a specific item. + In JSON-LD such data can be specified by associating the + @index keyword with a + @container declaration in the context:

+ + + +

In the example above, the athletes term has + been marked as an index map. + The catcher and pitcher keys will be ignored semantically, + but preserved syntactically, by the JSON-LD Processor. + If used in JavaScript, this can allow a developer to access a particular athlete using the + following code snippet: obj.athletes.pitcher.

+ +

The interpretation of the data is expressed in the statements table. + Note how the index keys do not appear in the statements, + but would continue to exist if the document were compacted or + expanded (see § 5.2 Compacted Document Form and + § 5.1 Expanded Document Form) using a JSON-LD processor.

+ +
Warning

As data indexes are not preserved when round-tripping to RDF; + this feature should be used judiciously. + Often, other indexing mechanisms, which are preserved, are more appropriate.

+ +

The value of @container can also + be an array containing both @index and @set. + When compacting, this ensures that a JSON-LD Processor will use + the array form for all values of indexes.

+ +

Unless the processing mode is set to json-ld-1.0, + the special index @none is used for indexing + data which does not have an associated index, which is useful to maintain + a normalized representation.

+ + + +
4.6.1.1 Property-based data indexing

This section is non-normative.

+

In its simplest form (as in the examples above), + data indexing assigns no semantics to the keys of an index map. + However, in some situations, + the keys used to index objects are semantically linked to these objects, + and should be preserved not only syntactically, but also semantically. +

+

Unless the processing mode is set to json-ld-1.0, + "@container": "@index" in a term description can be accompanied with + an "@index" key. The value of that key must map to an IRI, + which identifies the semantic property linking each object to its key. +

+ + +
Note

When using property-based data indexing, index maps can only be used + on node objects, not value objects or graph objects. + Value objects are restricted to have only certain keys and do not support + arbitrary properties.

+
+ +
+

4.6.2 Language Indexing

This section is non-normative.

+ +

JSON which includes string values in multiple languages may be + represented using a language map to allow for easily + indexing property values by language tag. This enables direct access to + language values instead of having to scan an array in search of a specific item. + In JSON-LD such data can be specified by associating the + @language keyword with a + @container declaration in the context:

+ + + +

In the example above, the label term has + been marked as a language map. The en and + de keys are implicitly associated with their respective + values by the JSON-LD Processor. This allows a developer to + access the German version of the label using the + following code snippet: obj.label.de, + which, again, is only appropriate when languages are limited to the + primary language sub-tag and do not depend on other sub-tags, such as "de-at".

+ +

The value of @container can also + be an array containing both @language and @set. + When compacting, this ensures that a JSON-LD Processor will use + the array form for all values of language tags.

+ + + +

Unless the processing mode is set to json-ld-1.0, + the special index @none is used for indexing + strings which do not have a language; this is useful to maintain + a normalized representation for string values not having a datatype.

+ + +
+

4.6.3 Node Identifier Indexing

This section is non-normative.

+ +

In addition to index maps, JSON-LD introduces the notion of id maps + for structuring data. The id indexing feature allows an author to + structure data using a simple key-value map where the keys map + to IRIs. This enables direct access to associated node objects + instead of having to scan an array in search of a specific item. + In JSON-LD such data can be specified by associating the + @id keyword with a + @container declaration in the context:

+ + + +

In the example above, the post term has + been marked as an id map. The http://example.com/posts/1/en and + http://example.com/posts/1/de keys will be interpreted + as the @id property of the node object value.

+ +

The interpretation of the data above is exactly the same + as that in § 4.6.1 Data Indexing + using a JSON-LD processor.

+ +

The value of @container can also + be an array containing both @id and @set. + When compacting, this ensures that a JSON-LD processor will use + the array form for all values of node identifiers.

+ + + +

The special index @none is used for indexing + node objects which do not have an @id, which is useful to maintain + a normalized representation. The @none index may also be + a term which expands to @none, such as the term none + used in the example below.

+ + + +
Note

Id maps are a new feature in JSON-LD 1.1.

+
+

4.6.4 Node Type Indexing

This section is non-normative.

+ +

In addition to id and index maps, JSON-LD introduces the notion of type maps + for structuring data. The type indexing feature allows an author to + structure data using a simple key-value map where the keys map + to IRIs. This enables data to be structured based on the @type + of specific node objects. + In JSON-LD such data can be specified by associating the + @type keyword with a + @container declaration in the context:

+ + + +

In the example above, the affiliation term has + been marked as a type map. The schema:Corporation and + schema:ProfessionalService keys will be interpreted + as the @type property of the node object value.

+ +

The value of @container can also + be an array containing both @type and @set. + When compacting, this ensures that a JSON-LD processor will use + the array form for all values of types.

+ + + +

The special index @none is used for indexing + node objects which do not have an @type, which is useful to maintain + a normalized representation. The @none index may also be + a term which expands to @none, such as the term none + used in the example below.

+ + + +

As with id maps, when used with @type, a container may also + include @set to ensure that key values are always contained in an array.

+ +
Note

Type maps are a new feature in JSON-LD 1.1.

+
+
+ +

4.7 Included Nodes

This section is non-normative.

+

Sometimes it is also useful to list node objects as part of another node object. + For instance, to represent a set of resources which are used by some other + resource. Included blocks may be also be used to collect such secondary node objects + which can be referenced from a primary node object. + For an example, consider a node object containing a list of different items, + some of which share some common elements:

+ +
+
+ Example 109: Included Blocks + 
{
+  "@context": {
+    "@version": 1.1,
+    "@vocab": "http://example.org/",
+    "classification": {"@type": "@vocab"}
+  },
+  "@id": "http://example.org/org-1",
+  "members": [{
+    "@id":"http://example.org/person-1",
+    "name": "Manu Sporny",
+    "classification": "employee"
+  }, {
+    "@id":"http://example.org/person-2",
+    "name": "Dave Longley",
+    "classification": "employee"
+  }, {
+    "@id": "http://example.org/person-3",
+    "name": "Gregg Kellogg",
+    "classification": "contractor"
+  }],
+  "@included": [{
+    "@id": "http://example.org/employee",
+    "label": "An Employee"
+  }, {
+    "@id": "http://example.org/contractor",
+    "label": "A Contractor"
+  }]
+}
+
+ +

When flattened, this will move the employee and contractor elements + from the included block into the outer array.

+ + + +

Included resources are described in + Inclusion of Related Resources of JSON API [JSON.API] + as a way to include related resources associated with some primary resource; + @included provides an analogous possibility in JSON-LD.

+ +

As a by product of the use of @included within node objects, a map may contain + only @included, to provide a feature similar to that described in § 4.1 Advanced Context Usage, + where @graph is used to described disconnected nodes.

+ + + +

However, in contrast to @graph, @included does not interact with other properties + contained within the same map, a feature discussed further in § 4.9 Named Graphs.

+
+ +

4.8 Reverse Properties

This section is non-normative.

+ +

JSON-LD serializes directed graphs. That means that + every property points from a node to another node + or value. However, in some cases, it is desirable + to serialize in the reverse direction. Consider for example the case where a person + and its children should be described in a document. If the used vocabulary does not + provide a children property but just a parent + property, every node representing a child would have to + be expressed with a property pointing to the parent as in the following + example.

+ + + +

Expressing such data is much simpler by using JSON-LD's @reverse + keyword:

+ + + +

The @reverse keyword can also be used in + expanded term definitions + to create reverse properties as shown in the following example:

+ + +
+ +

4.9 Named Graphs

This section is non-normative.

+ +

At times, it is necessary to make statements about a graph + itself, rather than just a single node. This can be done by + grouping a set of nodes using the @graph + keyword. A developer may also name data expressed using the + @graph keyword by pairing it with an + @id keyword as shown in the following example:

+ + + +

The example above expresses a named graph that is identified + by the IRI http://example.org/foaf-graph. That + graph is composed of the statements about Manu and Gregg. Metadata about + the graph itself is expressed via the generatedAt property, + which specifies when the graph was generated.

+ +

When a JSON-LD document's top-level structure is a + map that contains no other + keys than @graph and + optionally @context (properties that are not mapped to an + IRI or a keyword are ignored), + @graph is considered to express the otherwise implicit + default graph. This mechanism can be useful when a number + of nodes exist at the document's top level that + share the same context, which is, e.g., the case when a + document is flattened. The + @graph keyword collects such nodes in an array + and allows the use of a shared context.

+ + + +

In this case, embedding can not be used as + the graph contains unrelated nodes. + This is equivalent to using multiple + node objects in array and defining + the @context within each node object:

+ + + +
+

4.9.1 Graph Containers

This section is non-normative.

+

In some cases, it is useful to logically partition data into separate + graphs, without making this explicit within the JSON expression. For + example, a JSON document may contain data against which other metadata is + asserted and it is useful to separate this data in the data model using + the notion of named graphs, without the syntactic overhead + associated with the @graph keyword.

+ +

An expanded term definition can use @graph as the + value of @container. This indicates that values of this + term should be considered to be named graphs, where the + graph name is an automatically assigned blank node identifier + creating an implicitly named graph. When expanded, these become + simple graph objects.

+ +

A different example uses an anonymously named graph as follows:

+ + + +

The example above expresses an anonymously named graph + making a statement. The default graph includes a statement + saying that the subject wrote that statement. + This is an example of separating statements into a named graph, and then + making assertions about the statements contained within that named graph.

+ +
Note

Strictly speaking, the value of such a term + is not a named graph, rather it is the graph name + associated with the named graph, which exists separately within + the dataset.

+ +
Note

Graph Containers are a new feature in JSON-LD 1.1.

+
+ +

4.9.2 Named Graph Data Indexing

This section is non-normative.

+ +

In addition to indexing node objects by index, graph objects may + also be indexed by an index. By using the @graph + container type, introduced in § 4.9.1 Graph Containers + in addition to @index, an object value of such a property is + treated as a key-value map where the keys do not map to IRIs, but + are taken from an @index property associated with named graphs + which are their values. When expanded, these must be simple graph objects

+ +

The following example describes a default graph referencing multiple named + graphs using an index map.

+ + + +

As with index maps, when used with @graph, a container may also + include @set to ensure that key values are always contained in an array.

+ +

The special index @none is used for indexing + graphs which do not have an @index key, which is useful to maintain + a normalized representation. Note, however, that + compacting a document where multiple unidentified named graphs are + compacted using the @none index will result in the content + of those graphs being merged. To prevent this, give each graph a distinct + @index key.

+ + +
Note

Named Graph Data Indexing is a new feature in JSON-LD 1.1.

+
+ +

4.9.3 Named Graph Indexing

This section is non-normative.

+ +

In addition to indexing node objects by identifier, graph objects may + also be indexed by their graph name. By using the @graph + container type, introduced in § 4.9.1 Graph Containers + in addition to @id, an object value of such a property is + treated as a key-value map where the keys represent the identifiers of named graphs + which are their values.

+ +

The following example describes a default graph referencing multiple named + graphs using an id map.

+ + + +

As with id maps, when used with @graph, a container may also + include @set to ensure that key values are always contained in an array.

+ +

As with id maps, the special index @none is used for indexing + named graphs which do not have an @id, which is useful to maintain + a normalized representation. The @none index may also be + a term which expands to @none. + Note, however, that if multiple graphs are represented without + an @id, they will be merged on expansion. To prevent this, + use @none judiciously, and consider giving graphs + their own distinct identifier.

+ + + +
Note

Graph Containers are a new feature in JSON-LD 1.1.

+
+
+ +

4.10 Loading Documents

This section is non-normative.

+

The JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] + defines the interface to a JSON-LD Processor and includes + a number of methods used for manipulating different forms + of JSON-LD (see § 5. Forms of JSON-LD). + This includes a general mechanism for loading remote documents, + including referenced JSON-LD documents and remote contexts, + and potentially extracting embedded JSON-LD from other formats such as [HTML]. + This is more fully described in + Remote Document and Context Retrieval + in [JSON-LD11-API].

+ +

A documentLoader + can be useful in a number of contexts where loading remote documents can be problematic:

+
    +
  • Remote context documents should be cached to prevent overloading the + location of the remote context for each request. + Normally, an HTTP caching infrastructure might be expected to handle this, + but in some contexts this might not be feasible. + A documentLoader implementation might provide separate logic for performing + such caching.
    • +
  • Non-standard URL schemes may not be widely implemented, + or may have behavior specific to a given application domain. + A documentLoader can be defined to implement document retrieval semantics.
    • +
  • Certain well-known contexts may be statically cached within a documentLoader implementation. + This might be particularly useful in embedded applications, + where it is not feasible, or even possible, to access remote documents.
    • +
  • For security purposes, the act of remotely retrieving a document may provide a signal of application behavior. + The judicious use of a documentLoader can isolate the application and reduce its online fingerprint.
    • +
+
+
+ +

5. Forms of JSON-LD

This section is non-normative.

+

As with many data formats, there is no single correct way to describe data in JSON-LD. + However, as JSON-LD is used for describing graphs, certain transformations can be used + to change the shape of the data, without changing its meaning as Linked Data.

+ +
+
Expanded Document Form
+
Expansion is the process of taking a JSON-LD document and applying a + context so that the @context is no longer necessary. + This process is described further in § 5.1 Expanded Document Form.
+
Compacted Document Form
+
Compaction is the process + of applying a provided context to an existing JSON-LD document. This process + is described further in § 5.2 Compacted Document Form.
+
Flattened Document Form
+
Flattening is the process of extracting + embedded nodes to the top level of the JSON tree, and replacing the embedded + node with a reference, creating blank node identifiers as necessary. This + process is described further in § 5.3 Flattened Document Form.
+
Framed Document Form
+
Framing is used to shape + the data in a JSON-LD document, using an example frame document + which is used to both match the flattened data and show an example + of how the resulting data should be shaped. This + process is described further in § 5.4 Framed Document Form.
+
+ +

5.1 Expanded Document Form

This section is non-normative.

+ +

The JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] + defines a method for expanding a JSON-LD document. + Expansion is the process of taking a JSON-LD document and applying a + context such that all IRIs, types, and values + are expanded so that the @context is no longer necessary.

+ +

For example, assume the following JSON-LD input document:

+ +
+
+ Example 123: Sample JSON-LD document to be expanded + 
{
+   "@context": {
+      "name": "http://xmlns.com/foaf/0.1/name",
+      "homepage": {
+        "@id": "http://xmlns.com/foaf/0.1/homepage",
+        "@type": "@id"
+      }
+   },
+   "name": "Manu Sporny",
+   "homepage": "http://manu.sporny.org/"
+}
+
+ +

Running the JSON-LD Expansion algorithm against the JSON-LD input document + provided above would result in the following output:

+ + + +

JSON-LD's media type defines a + profile parameter which can be used to signal or request + expanded document form. The profile URI identifying + expanded document form is http://www.w3.org/ns/json-ld#expanded.

+
+ +

5.2 Compacted Document Form

This section is non-normative.

+ +

The JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] defines + a method for compacting a JSON-LD document. Compaction is the process + of applying a developer-supplied context to shorten IRIs + to terms or compact IRIs + and JSON-LD values expressed in expanded form to simple values such as + strings or numbers. + Often this makes it simpler to work with document as the data is expressed in + application-specific terms. Compacted documents are also typically easier to read + for humans.

+ +

For example, assume the following JSON-LD input document:

+ +
+
+ Example 125: Sample expanded JSON-LD document + 
[
+  {
+    "http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],
+    "http://xmlns.com/foaf/0.1/homepage": [
+      {
+       "@id": "http://manu.sporny.org/"
+      }
+    ]
+  }
+]
+
+ +

Additionally, assume the following developer-supplied JSON-LD context:

+ +
+
+ Example 126: Sample context + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "homepage": {
+      "@id": "http://xmlns.com/foaf/0.1/homepage",
+      "@type": "@id"
+    }
+  }
+}
+
+ +

Running the JSON-LD Compaction algorithm given the context supplied above + against the JSON-LD input document provided above would result in the following + output:

+ + + +

JSON-LD's media type defines a + profile parameter which can be used to signal or request + compacted document form. The profile URI identifying + compacted document form is http://www.w3.org/ns/json-ld#compacted.

+ +

The details of Compaction are described in the + Compaction algorithm in [JSON-LD11-API]. + This section provides a short description of how the algorithm operates as a guide + to authors creating contexts to be used for compacting JSON-LD documents.

+

The purpose of compaction is to apply the term definitions, vocabulary mapping, default language, + and base IRI to an existing JSON-LD document to cause it to be represented in a form + that is tailored to the use of the JSON-LD document directly as JSON. + This includes representing values as strings, rather than value objects, where possible, + shortening the use of list objects into simple arrays, reversing the relationship + between nodes, and using data maps to index into multiple values instead of + representing them as an array of values.

+ +

5.2.1 Shortening IRIs

This section is non-normative.

+

In an expanded JSON-LD document, IRIs are always represented as absolute IRIs. + In many cases, it is preferable to use a shorter version, either a relative IRI reference, + compact IRI, or term. Compaction uses a combination of elements + in a context to create a shorter form of these IRIs. See + § 4.1.2 Default Vocabulary, + § 4.1.3 Base IRI, + and § 4.1.5 Compact IRIs for more details.

+

The vocabulary mapping can be used to shorten IRIs that may be vocabulary relative + by removing the IRI prefix that matches the vocabulary mapping. + This is done whenever an IRI is determined to be vocabulary relative, + i.e., used as a property, or a value of @type, + or as the value of a term described as "@type": "@vocab".

+ + + + +
+ +

5.2.2 Representing Values as Strings

This section is non-normative.

+

To be unambiguous, the expanded document form always represents nodes + and values using node objects and value objects. + Moreover, property values are always contained within an array, even when there is only + one value. Sometimes this is useful to maintain a uniformity of access, + but most JSON data use the simplest possible representation, meaning that + properties have single values, which are represented as strings + or as structured values such as node objects. + By default, compaction will represent values which are simple strings as strings, + but sometimes a value is an IRI, a date, or some other typed value for which + a simple string representation would loose information. + By specifying this within a term definition, + the semantics of a string value can be inferred from the definition + of the term used as a property. + See § 4.2 Describing Values for more details.

+ + +
+ +

5.2.3 Representing Lists as Arrays

This section is non-normative.

+

As described in § 4.3.1 Lists, + JSON-LD has an expanded syntax for representing ordered values, + using the @list keyword. + To simplify the representation in JSON-LD, a term can be defined with + "@container": "@list" which causes all values of a + property using such a term to be considered ordered.

+ + +
+ +

5.2.4 Reversing Node Relationships

This section is non-normative.

+

In some cases, the property used to relate two nodes may + be better expressed if the nodes have a reverse direction, + for example, when describing a relationship between + two people and a common parent. + See § 4.8 Reverse Properties for more details.

+ + + +

Reverse properties can be even more useful when combined with + framing, which can actually make node objects defined + at the top-level of a document to become embedded nodes. + JSON-LD provides a means to index such values, by defining + an appropriate @container definition within a term definition.

+
+ +

5.2.5 Indexing Values

This section is non-normative.

+

Properties with multiple values are typically represented using + an unordered array. This means that an application working + on an internalized representation of that JSON would need to + iterate through the values of the array to find a value matching + a particular pattern, such as a language-tagged string + using the language en.

+ + + +

Data can be indexed on a number of different keys, including + @id, @type, @language, @index and more. + See § 4.6 Indexed Values and + § 4.9 Named Graphs for more details.

+
+ +

5.2.6 Normalizing Values as Objects

This section is non-normative.

+

Sometimes it's useful to compact a document, but keep the + node object and value object representations. + For this, a term definition can set "@type": "@none". + This causes the Value Compaction algorithm to always use the object + form of values, although components of that value may be compacted.

+ + +
+ +

5.2.7 Representing Singular Values as Arrays

This section is non-normative.

+

Generally, when compacting, properties having only one value are + represented as strings or maps, while properties having + multiple values are represented as an array of strings or maps. + This means that applications accessing such properties need to be prepared + to accept either representation. To force all values to be represented + using an array, a term definition can set "@container": "@set". + Moreover, @set can be used in combination with other container settings, + for example looking at our language-map example from § 5.2.5 Indexing Values:

+ + +
+ +

5.2.8 Term Selection

This section is non-normative.

+

When compacting, the Compaction algorithm will compact using a term + for a property only when the values of that property match the + @container, @type, and @language specifications for that term definition. + This can actually split values between different properties, all of which + have the same IRI. In case there is no matching term definition, + the compaction algorithm will compact using the absolute IRI of the property.

+ + +
+
+ +

5.3 Flattened Document Form

This section is non-normative.

+ +

The JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] defines + a method for flattening a JSON-LD document. + Flattening collects all + properties of a node in a single map and labels + all blank nodes with + blank node identifiers. + This ensures a shape of the data and consequently may drastically simplify the code + required to process JSON-LD in certain applications.

+ +

For example, assume the following JSON-LD input document:

+ +
+
+ Example 137: Sample JSON-LD document to be flattened + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "knows": "http://xmlns.com/foaf/0.1/knows"
+  },
+  "@id": "http://me.markus-lanthaler.com/",
+  "name": "Markus Lanthaler",
+  "knows": [
+    {
+      "@id": "http://manu.sporny.org/about#manu",
+      "name": "Manu Sporny"
+    }, {
+      "name": "Dave Longley"
+    }
+  ]
+}
+
+ +

Running the JSON-LD Flattening algorithm against the JSON-LD input document in + the example above and using the same context would result in the following + output:

+ + + +

JSON-LD's media type defines a + profile parameter which can be used to signal or request + flattened document form. The profile URI identifying + flattened document form is http://www.w3.org/ns/json-ld#flattened. + It can be combined with the profile URI identifying + expanded document form or + compacted document form.

+
+ +

5.4 Framed Document Form

This section is non-normative.

+ +

The JSON-LD 1.1 Framing specification [JSON-LD11-FRAMING] defines + a method for framing a JSON-LD document. Framing is used to shape + the data in a JSON-LD document, using an example frame document + which is used to both match the flattened data and show an example + of how the resulting data should be shaped.

+ +

For example, assume the following JSON-LD frame:

+ +
+
+ Example 139: Sample library frame + 
{
+  "@context": {
+    "@version": 1.1,
+    "@vocab": "http://example.org/"
+  },
+  "@type": "Library",
+  "contains": {
+    "@type": "Book",
+    "contains": {
+      "@type": "Chapter"
+    }
+  }
+}
+
+ +

This frame document describes an embedding structure that would place + objects with type Library at the top, with objects of + type Book that were linked to the library object using + the contains property embedded as property values. It also + places objects of type Chapter within the referencing Book object + as embedded values of the Book object.

+ +

When using a flattened set of objects that match the frame components:

+ +
+
+ Example 140: Flattened library objects + 
{
+  "@context": {
+    "@vocab": "http://example.org/",
+    "contains": {"@type": "@id"}
+  },
+  "@graph": [{
+    "@id": "http://example.org/library",
+    "@type": "Library",
+    "contains": "http://example.org/library/the-republic"
+  }, {
+    "@id": "http://example.org/library/the-republic",
+    "@type": "Book",
+    "creator": "Plato",
+    "title": "The Republic",
+    "contains": "http://example.org/library/the-republic#introduction"
+  }, {
+    "@id": "http://example.org/library/the-republic#introduction",
+    "@type": "Chapter",
+    "description": "An introductory chapter on The Republic.",
+    "title": "The Introduction"
+  }]
+}
+
+ +

The Frame Algorithm can create a new document which follows the structure + of the frame:

+ + + +

JSON-LD's media type defines a + profile parameter which can be used to signal or request + framed document form. The profile URI identifying + framed document form is http://www.w3.org/ns/json-ld#framed.

+ +

JSON-LD's media type also defines a + profile parameter which can be used to identify a + script element in an HTML document containing a frame. + The first script element + of type application/ld+json;profile=http://www.w3.org/ns/json-ld#frame + will be used to find a frame..

+
+
+ + + +

7. Embedding JSON-LD in HTML Documents

+ +
Note

This section describes features available + with a documentLoader supporting HTML script extraction. + See Remote Document and Context Retrieval + for more information.

+ +

+ JSON-LD content can be easily embedded in HTML [HTML] by placing + it in a script element with the type attribute set to + application/ld+json. Doing so creates a + data block.

+ + + +

Defining how such data may be used is beyond the scope of this specification. + The embedded JSON-LD document might be extracted as is or, e.g., be + interpreted as RDF.

+ +

If JSON-LD content is extracted as RDF [RDF11-CONCEPTS], it MUST be expanded into an + RDF Dataset using the + Deserialize JSON-LD to RDF Algorithm + [JSON-LD11-API]. Unless a specific script is targeted + (see § 7.3 Locating a Specific JSON-LD Script Element), + all script elements + with type application/ld+json MUST be processed and merged + into a single dataset with equivalent blank node identifiers contained in + separate script elements treated as if they were in a single document (i.e., + blank nodes are shared between different JSON-LD script elements).

+ + + +

7.1 Inheriting base IRI from HTML's base element

+

When processing a JSON-LD + script element, + the Document Base URL + of the containing HTML document, + as defined in [HTML], + is used to establish the default base IRI of the enclosed + JSON-LD content.

+ + + +

HTML allows for Dynamic changes to base URLs. + This specification does not require any specific behavior, + and to ensure that all systems process the base IRI equivalently, authors SHOULD + either use IRIs, or explicitly as defined in § 4.1.3 Base IRI. + Implementations (particularly those natively operating in the [DOM]) MAY take into consideration + Dynamic changes to base URLs.

+
+ +

7.2 Restrictions for contents of JSON-LD script elements

This section is non-normative.

+

Due to the HTML Restrictions for contents of <script> elements + additional encoding restrictions are placed on JSON-LD data contained in + script elements.

+

Authors should avoid using character sequences in scripts embedded in HTML + which may be confused with a comment-open, script-open, + comment-close, or script-close.

+
Note
Such content should be escaped as indicated below, however + the content will remain escaped after processing through the + JSON-LD API [JSON-LD11-API]. +
    +
  • &amp; → & (ampersand, U+0026)
    • +
  • &lt; → < (less-than sign, U+003C)
    • +
  • &gt; → > (greater-than sign, U+003E)
    • +
  • &quot; → " (quotation mark, U+0022)
    • +
  • &apos; → ' (apostrophe, U+0027)
    • +
+
+ + +
+ +

7.3 Locating a Specific JSON-LD Script Element

+

A specific + script element + within an HTML document may be located using + a fragment identifier matching the unique identifier + of the script element within the HTML document located by a URL (see [DOM]). + A JSON-LD processor MUST extract only the specified data block's contents + parsing it as a standalone JSON-LD document + and MUST NOT merge the result with any other markup from the same HTML document.

+ +

For example, given an HTML document located at http://example.com/document, + a script element identified by "dave" can be targeted using the URL + http://example.com/document#dave.

+ + +
+
+ +
+

8. Data Model

+ +

JSON-LD is a serialization format for Linked Data based on JSON. + It is therefore important to distinguish between the syntax, which is + defined by JSON in [RFC8259], and the data model which is + an extension of the RDF data model [RDF11-CONCEPTS]. + The precise details of how JSON-LD relates to the RDF data model are given in + § 10. Relationship to RDF.

+ +

To ease understanding for developers unfamiliar with the RDF model, the + following summary is provided:

+ + + +

JSON-LD documents MAY contain data + that cannot be represented by the data model + defined above. Unless otherwise specified, such data is ignored when a + JSON-LD document is being processed. One result of this rule + is that properties which are not mapped to an IRI, + a blank node, or keyword will be ignored.

+ +

Additionally, the JSON serialization format is internally represented using + the JSON-LD internal representation, which uses the generic + concepts of lists, maps, + strings, numbers, booleans, and null to describe + the data represented by a JSON document.

+ +
+ + +

The image depicts a linked data dataset with a default graph + and two named graphs.

+ +
Figure 1 An illustration of a linked data dataset.
+ A description of the linked data dataset + diagram is available in the Appendix. Image available in + + SVG + and + + PNG + + formats.
+
+ +

The dataset described in this figure can be represented as follows:

+ + + +
Note

Note the use of @graph at the outer-most level to describe three top-level + resources (two of them named graphs). The named graphs use @graph in addition + to @id to provide the name for each graph.

+
+ +
+

9. JSON-LD Grammar

+ +

This section restates the syntactic conventions described in the + previous sections more formally.

+ +

A JSON-LD document MUST be valid JSON text as described + in [RFC8259], or some format that can be represented + in the JSON-LD internal representation that is equivalent to + valid JSON text.

+ +

A JSON-LD document MUST be a single node object, + a map consisting of only + the entries @context and/or @graph, + or an array of zero or more node objects.

+ +

In contrast to JSON, in JSON-LD the keys in objects + MUST be unique.

+ +

Whenever a keyword is discussed in this grammar, + the statements also apply to an alias for that keyword.

+ +
Note

JSON-LD allows keywords to be aliased + (see § 4.1.6 Aliasing Keywords for details). For example, if the active context + defines the term id as an alias for @id, + that alias may be legitimately used as a substitution for @id. + Note that keyword aliases are not expanded during context + processing.

+ +
+

9.1 Terms

+ +

A term is a short-hand string that expands + to an IRI, blank node identifier, or keyword.

+ +

A term MUST NOT equal any of the JSON-LD keywords, + other than @type.

+ +

When used as the prefix in a Compact IRI, to avoid + the potential ambiguity of a prefix being confused with an IRI + scheme, terms SHOULD NOT come from the list of URI schemes as defined in + [IANA-URI-SCHEMES]. Similarly, to avoid confusion between a + Compact IRI and a term, terms SHOULD NOT include a colon (:) + and SHOULD be restricted to the form of + isegment-nz-nc + as defined in [RFC3987].

+ +

To avoid forward-compatibility issues, a term SHOULD NOT start + with an @ character + followed exclusively by one or more ALPHA characters (see [RFC5234]) + as future versions of JSON-LD may introduce + additional keywords. Furthermore, the term MUST NOT + be an empty string ("") as not all programming languages + are able to handle empty JSON keys.

+ +

See § 3.1 The Context and + § 3.2 IRIs for further discussion + on mapping terms to IRIs.

+
+ +
+

9.2 Node Objects

+ +

A node object represents zero or more properties of a + node in the graph serialized by the + JSON-LD document. A map is a + node object if it exists outside of a JSON-LD + context and:

+ +
    +
  • it is not the top-most map in the JSON-LD document consisting + of no other entries than @graph and @context,
    • +
  • it does not contain the @value, @list, + or @set keywords, and
    • +
  • it is not a graph object.
    • +
+ +

The properties of a node in + a graph may be spread among different + node objects within a document. When + that happens, the keys of the different + node objects need to be merged to create the + properties of the resulting node.

+ +

A node object MUST be a map. All keys + which are not IRIs, compact IRIs, terms valid in the + active context, or one of the following keywords + (or alias of such a keyword) + MUST be ignored when processed:

+ +
    +
  • @context,
    • +
  • @id,
    • +
  • @included,
    • +
  • @graph,
    • +
  • @nest,
    • +
  • @type,
    • +
  • @reverse, or
    • +
  • @index
    • +
+ +

If the node object contains the @context + key, its value MUST be null, an IRI reference, + a context definition, or + an array composed of any of these.

+ +

If the node object contains the @id key, + its value MUST be an IRI reference, + or a compact IRI (including + blank node identifiers). + See § 3.3 Node Identifiers, + § 4.1.5 Compact IRIs, and + § 4.5.1 Identifying Blank Nodes for further discussion on + @id values.

+ +

If the node object contains the @graph + key, its value MUST be + a node object or + an array of zero or more node objects. + If the node object also contains an @id keyword, + its value is used as the graph name of a named graph. + See § 4.9 Named Graphs for further discussion on + @graph values. As a special case, if a map + contains no keys other than @graph and @context, and the + map is the root of the JSON-LD document, the + map is not treated as a node object; this + is used as a way of defining node objects + that may not form a connected graph. This allows a + context to be defined which is shared by all of the constituent + node objects.

+ +

If the node object contains the @type + key, its value MUST be either an IRI reference, a compact IRI + (including blank node identifiers), + a term defined in the active context expanding into an IRI, or + an array of any of these. + See § 3.5 Specifying the Type for further discussion on + @type values.

+ +

If the node object contains the @reverse key, + its value MUST be a map containing entries representing reverse + properties. Each value of such a reverse property MUST be an IRI reference, + a compact IRI, a blank node identifier, + a node object or an array containing a combination of these.

+ +

If the node object contains the @included key, + its value MUST be an included block. + See § 9.13 Included Blocks for further discussion + on included blocks.

+ +

If the node object contains the @index key, + its value MUST be a string. See + § 4.6.1 Data Indexing for further discussion + on @index values.

+ +

If the node object contains the @nest key, + its value MUST be a map or an array of map + which MUST NOT include a value object. See + § 9.14 Property Nesting for further discussion + on @nest values.

+ +

Keys in a node object that are not + keywords MAY expand to an IRI + using the active context. The values associated with keys that expand + to an IRI MUST be one of the following:

+ + +
+ +

9.3 Frame Objects

+

When framing, a frame object extends a node object to allow + entries used specifically for framing.

+ +

See [JSON-LD11-FRAMING] for a description of how frame objects are used.

+
+ +
+

9.4 Graph Objects

+ +

A graph object represents a named graph, which MAY include + an explicit graph name. + A map is a graph object if + it exists outside of a JSON-LD context, + it contains an @graph entry (or an alias of that keyword), + it is not the top-most map in the JSON-LD document, and + it consists of no entries other than @graph, + @index, @id + and @context, or an alias of one of these keywords.

+ +

If the graph object contains the @context + key, its value MUST be null, an IRI reference, a context definition, or + an array composed of any of these.

+ +

If the graph object contains the @id key, + its value is used as the identifier (graph name) of a named graph, and + MUST be an IRI reference, + or a compact IRI (including + blank node identifiers). + See § 3.3 Node Identifiers, + § 4.1.5 Compact IRIs, and + § 4.5.1 Identifying Blank Nodes for further discussion on + @id values.

+ +

A graph object without an @id entry is also a + simple graph object and represents a named graph without an + explicit identifier, although in the data model it still has a + graph name, which is an implicitly allocated + blank node identifier.

+ +

The value of the @graph key MUST be + a node object or + an array of zero or more node objects. + See § 4.9 Named Graphs for further discussion on + @graph values..

+
+ +
+

9.5 Value Objects

+ +

A value object is used to explicitly associate a type or a + language with a value to create a typed value or a language-tagged string + and possibly associate a base direction.

+ +

A value object MUST be a map containing the + @value key. It MAY also contain an @type, + an @language, + an @direction, + an @index, or an @context key but MUST NOT contain + both an @type and either @language + or @direction + keys at the same time. + A value object MUST NOT contain any other keys that expand to an + IRI or keyword.

+ +

The value associated with the @value key MUST be either a + string, a number, true, + false or null. + If the value associated with the @type key + is @json, the value MAY be either an array or an object.

+ +

The value associated with the @type key MUST be a + term, + an IRI, + a compact IRI, + a string which can be turned into an IRI using the vocabulary mapping, + @json, + or null.

+ +

The value associated with the @language key MUST have the + lexical form described in [BCP47], or be null.

+ +

The value associated with the @direction key MUST be + one of "ltr" or "rtl", or be null.

+ +

The value associated with the @index key MUST be a + string.

+ +

See § 4.2.1 Typed Values and + § 4.2.4 String Internationalization + for more information on value objects.

+
+ +
+

9.6 Value Patterns

+

When framing, + a value pattern + extends a value object to allow + entries used specifically for framing.

+ +
+ +
+

9.7 Lists and Sets

+ +

A list represents an ordered set of values. A set + represents an unordered set of values. Unless otherwise specified, + arrays are unordered in JSON-LD. As such, the + @set keyword, when used in the body of a JSON-LD document, + represents just syntactic sugar which is optimized away when processing the document. + However, it is very helpful when used within the context of a document. Values + of terms associated with an @set or @list container + will always be represented in the form of an array when a document + is processed—even if there is just a single value that would otherwise be optimized to + a non-array form in compacted document form. + This simplifies post-processing of the data as the data is always in a + deterministic form.

+ +

A list object MUST be a map that contains no + keys that expand to an IRI or keyword other + than @list and @index.

+ +

A set object MUST be a map that contains no + keys that expand to an IRI or keyword other + than @set and @index. + Please note that the @index key will be ignored when being processed.

+ +

In both cases, the value associated with the keys @list and @set + MUST be one of the following types:

+ + +

See § 4.3 Value Ordering for further discussion on sets and lists.

+
+ +
+

9.8 Language Maps

+ +

A language map is used to associate a language with a value in a + way that allows easy programmatic access. A language map may be + used as a term value within a node object if the term is defined + with @container set to @language, + + or an array containing both @language and @set + . The keys of a + language map MUST be strings representing + [BCP47] language tags, the keyword @none, + or a term which expands to @none, + and the values MUST be any of the following types:

+ + + +

See § 4.2.4 String Internationalization for further discussion + on language maps.

+
+ +
+

9.9 Index Maps

+ +

An index map allows keys that have no semantic meaning, + but should be preserved regardless, to be used in JSON-LD documents. + An index map may + be used as a term value within a node object if the + term is defined with @container set to @index, + + or an array containing both @index and @set + . + The values of the entries of an index map MUST be one + of the following types:

+ + + +

See § 4.6.1 Data Indexing for further information on this topic.

+ +

Index Maps may also be used to map indexes to associated + named graphs, if the term is defined with @container + set to an array containing both @graph and + @index, and optionally including @set. The + value consists of the node objects contained within the named + graph which is indexed using the referencing key, which can be + represented as a simple graph object if the value does + not include @id, or a named graph if it includes @id.

+
+ +
+

9.10 Property-based Index Maps

+ +

A property-based index map is a variant of index map + were indexes are semantically preserved in the graph as property values. + A property-based index map may be used as a term value within a node object + if the term is defined with @container set to @index, + or an array containing both @index and @set, + and with @index set to a string. + The values of a property-based index map MUST be node objects + or strings which expand to node objects.

+ +

When expanding, + if the active context contains a term definition + for the value of @index, + this term definition will be used to expand the keys of the index map. + Otherwise, the keys will be expanded as simple value objects. + Each node object in the expanded values of the index map + will be added an additional property value, + where the property is the expanded value of @index, + and the value is the expanded referencing key. +

+ +

See § 4.6.1.1 Property-based data indexing for further information on this topic.

+
+ +
+

9.11 Id Maps

+ +

An id map is used to associate an IRI with a value that allows easy + programmatic access. An id map may be used as a term value within a node object if the term + is defined with @container set to @id, + or an array containing both @id and @set. + The keys of an id map MUST be IRIs + (IRI references or compact IRIs (including blank node identifiers)), + the keyword @none, + or a term which expands to @none, + and the values MUST be node objects.

+ +

If the value contains a property expanding to @id, its value MUST + be equivalent to the referencing key. Otherwise, the property from the value is used as + the @id of the node object value when expanding.

+ +

Id Maps may also be used to map graph names to their + named graphs, if the term is defined with @container + set to an array containing both @graph and @id, + and optionally including @set. The value consists of the + node objects contained within the named graph + which is named using the referencing key.

+
+ +
+

9.12 Type Maps

+ +

A type map is used to associate an IRI with a value that allows easy + programmatic access. A type map may be used as a term value within a node object if the term + is defined with @container set to @type, + or an array containing both @type and @set. + The keys of a type map MUST be IRIs + (IRI references or compact IRI (including blank node identifiers)), + terms, + or the keyword @none, + and the values MUST be node objects + or strings which expand to node objects.

+ +

If the value contains a property expanding to @type, and its value + is contains the referencing key after suitable expansion of both the referencing key + and the value, then the node object already contains the type. Otherwise, the property from the value is + added as a @type of the node object value when expanding.

+
+ +
+

9.13 Included Blocks

+ +

An included block is used to provide a set of node objects. + An included block MAY appear as the value of a member of a node object with either the key of @included or an alias of @included. + An included block is either a node object or an array of node objects.

+ +

When expanding, multiple included blocks will be coalesced into a single included block.

+
+ +
+

9.14 Property Nesting

+ +

A nested property is used to gather properties of a node object in a separate + map, or array of maps which are not + value objects. It is semantically transparent and is removed + during the process of expansion. Property nesting is recursive, and + collections of nested properties may contain further nesting.

+ +

Semantically, nesting is treated as if the properties and values were declared directly + within the containing node object.

+
+ +
+

9.15 Context Definitions

+ +

A context definition defines a local context in a + node object.

+ +

A context definition MUST be a map whose + keys MUST be either terms, compact IRIs, IRIs, + or one of the keywords + @base, + @import, + @language, + @propagate, + @protected, + @type, + @version, + or @vocab. +

+ +

If the context definition has an @base key, + its value MUST be an IRI reference, + or null.

+ +

If the context definition has an @direction key, + its value MUST be one of "ltr" or "rtl", or be null.

+ +

If the context definition contains the @import + keyword, its value MUST be an IRI reference. + When used as a reference from an @import, the referenced context definition MUST NOT + include an @import key, itself.

+ +

If the context definition has an @language key, + its value MUST have the lexical form described in [BCP47] or be null.

+ +

If the context definition has an @propagate key, + its value MUST be true or false.

+ +

If the context definition has an @protected key, + its value MUST be true or false.

+ +

If the context definition has an @type key, + its value MUST be a map with only the entry @container set to @set, + and optionally an entry @protected.

+ +

If the context definition has an @version key, + its value MUST be a number with the value 1.1.

+ +

If the context definition has an @vocab key, + its value MUST be an IRI reference, a compact IRI, + a blank node identifier, + a term, or null.

+ +

The value of keys that are not keywords MUST be either an + IRI, a compact IRI, a term, + a blank node identifier, a keyword, null, + or an expanded term definition.

+ + +

9.15.1 Expanded term definition

+

An expanded term definition is used to describe the mapping + between a term and its expanded identifier, as well as other + properties of the value associated with the term when it is + used as key in a node object.

+ +

An expanded term definition MUST be a map + composed of zero or more keys from + @id, + @reverse, + @type, + @language, + @container, + @context, + @prefix, + @propagate, or + @protected. + An expanded term definition SHOULD NOT contain any other keys.

+ +

When the associated term is @type, the expanded term definition + MUST NOT contain keys other than @container and @protected. + The value of @container is limited to the single value @set.

+ +

If the term being defined is not an IRI or a compact IRI + and the active context does not have an + @vocab mapping, the expanded term definition MUST + include the @id key.

+ +

Term definitions with keys which are of the form of an IRI or a compact IRI MUST NOT + expand to an IRI other than the expansion of the key itself.

+ +

If the expanded term definition contains the @id + keyword, its value MUST be null, an IRI, + a blank node identifier, a compact IRI, a term, + or a keyword.

+ +

If an expanded term definition has an @reverse entry, + it MUST NOT have @id or @nest entries at the same time, + its value MUST be an IRI, + a blank node identifier, a compact IRI, or a term. If an + @container entry exists, its value MUST be null, + @set, or @index.

+ +

If the expanded term definition contains the @type + keyword, its value MUST be an IRI, a + compact IRI, a term, null, or one of the + keywords @id, @json, @none, or @vocab.

+ +

If the expanded term definition contains the @language keyword, + its value MUST have the lexical form described in [BCP47] or be null.

+ +

If the expanded term definition contains the @index + keyword, its value MUST be an IRI, + a compact IRI, or a term.

+ +

If the expanded term definition contains the @container + keyword, its value MUST be either + @list, + @set, + @language, + @index, + @id, + @graph, + @type, or be + null + + or an array containing exactly any one of those keywords, or a + combination of @set and any of @index, + @id, @graph, @type, + @language in any order + . + @container may also be an array + containing @graph along with either @id or + @index and also optionally including @set. + If the value + is @language, when the term is used outside of the + @context, the associated value MUST be a language map. + If the value is @index, when the term is used outside of + the @context, the associated value MUST be an + index map.

+ +

If an expanded term definition has an @context entry, + it MUST be a valid context definition.

+ +

If the expanded term definition contains the @nest + keyword, its value MUST be either @nest, or a term + which expands to @nest.

+ +

If the expanded term definition contains the @prefix + keyword, its value MUST be true or false.

+ +

If the expanded term definition contains the @propagate + keyword, its value MUST be true or false.

+ +

If the expanded term definition contains the @protected + keyword, its value MUST be true or false.

+ +

Terms MUST NOT be used in a circular manner. That is, + the definition of a term cannot depend on the definition of another term if that other + term also depends on the first term.

+ +
+ +

See § 3.1 The Context for further discussion on contexts.

+
+ +
+

9.16 Keywords

+

JSON-LD keywords are described in § 1.7 Syntax Tokens and Keywords, + this section describes where each keyword may appear within different JSON-LD structures.

+ +

Within + node objects, + value objects, + graph objects, + list objects, + set objects, and + nested properties + keyword aliases MAY be used instead of the corresponding keyword, except for @context. + The @context keyword MUST NOT be aliased. + Within local contexts and expanded term definitions, + keyword aliases MAY NOT used.

+ +
@base
+ The unaliased @base keyword MAY be used as a key in a context definition. + Its value MUST be an IRI reference, or null. +
+
@container
+ The unaliased @container keyword MAY be used as a key in an expanded term definition. + Its value MUST be either + @list, + @set, + @language, + @index, + @id, + @graph, + @type, or be + null, + or an array containing exactly any one of those keywords, or a + combination of @set and any of @index, + @id, @graph, @type, + @language in any order. + The value may also be an array + containing @graph along with either @id or + @index and also optionally including @set. +
+
@context
+ The @context keyword MUST NOT be aliased, and MAY be used as a key in the following objects: + + The value of @context MUST be + null, + an IRI reference, + a context definition, or + an array composed of any of these. +
+
@direction
+ The @direction keyword MAY be aliased and MAY be used as a key in a value object. + Its value MUST be one of "ltr" or "rtl", or be null. +

The unaliased @direction MAY be used as a key in a context definition.

+

See § 4.2.4.1 Base Direction for a further discussion.

+
+
@graph
+ The @graph keyword MAY be aliased and MAY be used as a key in a node object or a graph object, + where its value MUST be a value object, node object, or an array of either value objects or node objects. +

The unaliased @graph MAY be used as the value of the @container key within an expanded term definition.

+

See § 4.9 Named Graphs.

+
+
@id
+ The @id keyword MAY be aliased and MAY be used as a key in a node object or a graph object. +

The unaliased @id MAY be used as a key in an expanded term definition, + or as the value of the @container key within an expanded term definition.

+

The value of the @id key MUST be an IRI reference, + or a compact IRI (including blank node identifiers).

+

See § 3.3 Node Identifiers, + § 4.1.5 Compact IRIs, and + § 4.5.1 Identifying Blank Nodes for further discussion on + @id values.

+
+
@import
+ The unaliased @import keyword MAY be used in a context definition. + Its value MUST be an IRI reference. + See § 4.1.10 Imported Contexts for a further discussion. +
+
@included
+ The @included keyword MAY be aliased and + its value MUST be an included block. + This keyword is described further in § 4.7 Included Nodes, + and § 9.13 Included Blocks. +
+
@index
+ The @index keyword MAY be aliased and MAY be used as a key in a + node object, value object, graph object, set object, or list object. + Its value MUST be a string. +

The unaliased @index MAY be used as the value of the @container key within an expanded term definition + and as an entry in a expanded term definition, where the value an IRI, + a compact IRI, or a term.

+

See § 9.9 Index Maps, and + § 4.6.1.1 Property-based data indexing for a further discussion.

+
+
@json
+ The @json keyword MAY be aliased + and MAY be used as the value of the @type key within a value object + or an expanded term definition. +

See § 4.2.2 JSON Literals.

+
@language
+ The @language keyword MAY be aliased and MAY be used as a key in a value object. + Its value MUST be a string with the lexical form described in [BCP47] or be null. +

The unaliased @language MAY be used as a key in a context definition, + or as the value of the @container key within an expanded term definition.

+

See § 4.2.4 String Internationalization, § 9.8 Language Maps.

+
+
@list
+ The @list keyword MAY be aliased and MUST be used as a key in a list object. + The unaliased @list MAY be used as the value of the @container key within an expanded term definition. + Its value MUST be one of the following: + + +

See § 4.3 Value Ordering for further discussion on sets and lists.

+
+
@nest
+ The @nest keyword MAY be aliased and MAY be used as a key in a node object, + where its value must be a map. +

The unaliased @nest MAY be used as the value of a simple term definition, + or as a key in an expanded term definition, + where its value MUST be a string expanding to @nest.

+

See § 9.14 Property Nesting for a further discussion.

+
+
@none
+ The @none keyword MAY be aliased and MAY be used as a key in an + index map, id map, language map, type map. + See § 4.6.1 Data Indexing, + § 4.6.2 Language Indexing, + § 4.6.3 Node Identifier Indexing, + § 4.6.4 Node Type Indexing, + § 4.9.3 Named Graph Indexing, or + § 4.9.2 Named Graph Data Indexing + for a further discussion.
+
@prefix
+ The unaliased @prefix keyword MAY be used as a key in an expanded term definition. + Its value MUST be true or false. + See § 4.1.5 Compact IRIs + and § 9.15 Context Definitions + for a further discussion. +
+
@propagate
+ The unaliased @propagate keyword MAY be used in a context definition. + Its value MUST be true or false. + See § 4.1.9 Context Propagation for a further discussion. +
+
@protected
+ The unaliased @protected keyword MAY be used in a context definition, + or an expanded term definition. + Its value MUST be true or false. + See § 4.1.11 Protected Term Definitions for a further discussion. +
+
@reverse
+ The @reverse keyword MAY be aliased and MAY be used as a key in a node object. +

The unaliased @reverse MAY be used as a key in an expanded term definition.

+

The value of the @reverse key MUST be an IRI reference, + or a compact IRI (including blank node identifiers).

+

See § 4.8 Reverse Properties and + § 9.15 Context Definitions for further discussion.

+
+
@set
+ The @set keyword MAY be aliased and MUST be used as a key in a set object. + Its value MUST be one of the following: + + +

The unaliased @set MAY be used as the value of the @container key within an expanded term definition.

+ +

See § 4.3 Value Ordering for further discussion on sets and lists.

+
+
@type
+ The @type keyword MAY be aliased and MAY be used as a key in a node object or a value object, + where its value MUST be a term, IRI reference, + or a compact IRI (including blank node identifiers). +

The unaliased @type MAY be used as a key in an expanded term definition, + where its value may also be either @id or @vocab, + or as the value of the @container key within an expanded term definition.

+

Within a context, @type may be used as the key for an expanded term definition, + whose entries are limited to @container and @protected.

+

This keyword is described further in § 3.5 Specifying the Type + and § 4.2.1 Typed Values.

+
+
@value
+ The @value keyword MAY be aliased and MUST be used as a key in a value object. + Its value key MUST be either a string, a number, true, false or null. + This keyword is described further in § 9.5 Value Objects. +
+
@version
+ The unaliased @version keyword MAY be used as a key in a context definition. + Its value MUST be a number with the value 1.1. + This keyword is described further in § 9.15 Context Definitions. +
+
@vocab
+ The unaliased @vocab keyword MAY be used as a key in a context definition + or as the value of @type in an expanded term definition. + Its value MUST be an IRI reference, a compact IRI, a blank node identifier, a term, or null. + This keyword is described further in § 9.15 Context Definitions, + and § 4.1.2 Default Vocabulary. +
+
+
+
+ +
+

10. Relationship to RDF

+ +

JSON-LD is a + concrete RDF syntax + as described in [RDF11-CONCEPTS]. Hence, a JSON-LD document is both an + RDF document and a JSON document and correspondingly represents an + instance of an RDF data model. However, JSON-LD also extends the RDF data + model to optionally allow JSON-LD to serialize + generalized RDF Datasets. + The JSON-LD extensions to the RDF data model are:

+ +
    +
  • In JSON-LD properties can be + IRIs or blank nodes + whereas in RDF properties (predicates) have to be IRIs. This + means that JSON-LD serializes + generalized RDF Datasets.
    • +
  • In JSON-LD lists use native JSON syntax, either contained in a + list object, or described as such within a context. Consequently, developers + using the JSON representation can access list elements directly rather than + using the vocabulary for collections described in [RDF-SCHEMA].
    • +
  • RDF values are either typed literals + (typed values) or + language-tagged strings whereas + JSON-LD also supports JSON's native data types, i.e., number, + strings, and the boolean values true + and false. The JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] + defines the conversion rules + between JSON's native data types and RDF's counterparts to allow round-tripping.
    • +
  • As an extension to the RDF data model, + literals without an explicit datatype + MAY include a base direction. + As there is currently no standardized mechanism for representing the base direction + of RDF literals, the JSON-LD to standard RDF transformation loses the base direction. + However, the Deserialize JSON-LD to RDF Algorithm + provides a means of representing base direction + using mechanisms which will preserve round-tripping through non-standard RDF.
    • +
+ +
Note

The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, as is the support for generalized RDF Datasets.

+ +

Summarized, these differences mean that JSON-LD is capable of serializing any RDF + graph or dataset and most, but not all, JSON-LD documents can be directly + interpreted as RDF as described in RDF 1.1 Concepts [RDF11-CONCEPTS].

+ +

Authors are strongly encouraged to avoid labeling properties using blank node identifiers, + instead, consider one of the following mechanisms:

+ + +

The normative algorithms for interpreting JSON-LD as RDF and serializing + RDF as JSON-LD are specified in the JSON-LD 1.1 Processing Algorithms and API + specification [JSON-LD11-API].

+ +

Even though JSON-LD serializes + RDF Datasets, it can + also be used as a graph source. + In that case, a consumer MUST only use the default graph and ignore all named graphs. + This allows servers to expose data in languages such as Turtle and JSON-LD + using HTTP content negotiation.

+ +
Note

Publishers supporting both dataset and graph syntaxes have to ensure that + the primary data is stored in the default graph to enable consumers that do not support + datasets to process the information.

+ +
+

10.1 Serializing/Deserializing RDF

This section is non-normative.

+ +

The process of serializing RDF as JSON-LD and deserializing JSON-LD to RDF + depends on executing the algorithms defined in + RDF Serialization-Deserialization Algorithms + in the JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API]. + It is beyond the scope of this document to detail these algorithms any further, + but a summary of the necessary operations is provided to illustrate the process.

+ +

The procedure to deserialize a JSON-LD document to RDF involves the + following steps:

+ +
    +
  1. Expand the JSON-LD document, removing any context; this ensures + that properties, types, and values are given their full representation + as IRIs and expanded values. Expansion + is discussed further in § 5.1 Expanded Document Form.
    2. +
  2. Flatten the document, which turns the document into an array of + node objects. Flattening is discussed + further in § 5.3 Flattened Document Form.
    3. +
  3. Turn each node object into a series of triples.
    4. +
+ +

For example, consider the following JSON-LD document in compact form:

+ +
+
+ Example 151: Sample JSON-LD document + 
{
+  "@context": {
+    "name": "http://xmlns.com/foaf/0.1/name",
+    "knows": "http://xmlns.com/foaf/0.1/knows"
+  },
+  "@id": "http://me.markus-lanthaler.com/",
+  "name": "Markus Lanthaler",
+  "knows": [
+    {
+      "@id": "http://manu.sporny.org/about#manu",
+      "name": "Manu Sporny"
+    }, {
+      "name": "Dave Longley"
+    }
+  ]
+}
+
+ +

Running the JSON-LD Expansion and Flattening algorithms against the + JSON-LD input document in the example above would result in the + following output:

+ +
+
+ Example 152: Flattened and expanded form for the previous example + 
[
+  {
+    "@id": "_:b0",
+    "http://xmlns.com/foaf/0.1/name": "Dave Longley"
+  }, {
+    "@id": "http://manu.sporny.org/about#manu",
+    "http://xmlns.com/foaf/0.1/name": "Manu Sporny"
+  }, {
+    "@id": "http://me.markus-lanthaler.com/",
+    "http://xmlns.com/foaf/0.1/name": "Markus Lanthaler",
+    "http://xmlns.com/foaf/0.1/knows": [
+      { "@id": "http://manu.sporny.org/about#manu" },
+      { "@id": "_:b0" }
+    ]
+  }
+]
+
+ +

Deserializing this to RDF now is a straightforward process of turning + each node object into one or more triples. This can be + expressed in Turtle as follows:

+ +
+
+ Example 153: Turtle representation of expanded/flattened document + 
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+_:b0 foaf:name "Dave Longley" .
+
+<http://manu.sporny.org/about#manu> foaf:name "Manu Sporny" .
+
+<http://me.markus-lanthaler.com/> foaf:name "Markus Lanthaler" ;
+    foaf:knows <http://manu.sporny.org/about#manu>, _:b0 .
+
+ +

The process of serializing RDF as JSON-LD can be thought of as the + inverse of this last step, creating an expanded JSON-LD document closely + matching the triples from RDF, using a single node object + for all triples having a common subject, and a single property + for those triples also having a common predicate. The result may + then be framed by using the + Framing Algorithm + described in [JSON-LD11-FRAMING] to create the desired object embedding.

+
+ +

10.2 The rdf:JSON Datatype

+

RDF provides for JSON content as a possible literal value. + This allows markup in literal values. + Such content is indicated in a graph using a literal whose datatype is set to rdf:JSON.

+ +

The rdf:JSON datatype is defined as follows:

+ +
+
The IRI denoting this datatype
+
is http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON.
+
The lexical space
+
is the set of UNICODE [UNICODE] strings which conform to the JSON Grammar + as described in Section 2 JSON Grammar of [RFC8259].
+
The value space
+
is the set of UNICODE [UNICODE] strings which conform to the JSON Grammar + as described in Section 2 JSON Grammar of [RFC8259], + and furthermore comply with the following constraints: +
    +
  • It MUST NOT contain any unnecessary whitespace,
    • +
  • Keys in objects MUST be ordered lexicographically,
    • +
  • Native Numeric values MUST be serialized according to + Section 7.1.12.1 of [ECMASCRIPT],
    • +
  • Strings MUST be serialized with Unicode codepoints from U+0000 through U+001F + using lower case hexadecimal Unicode notation (\uhhhh) unless in the set + of predefined JSON control characters U+0008, U+0009, + U+000A, U+000C or U+000D + which SHOULD be serialized as \b, \t, \n, \f and \r respectively. + All other Unicode characters SHOULD be serialized "as is", other than + U+005C (\) and U+0022 (") + which SHOULD be serialized as \\ and \" respectively.
    • +
+
Issue
The JSON Canonicalization Scheme (JCS) [RFC8785] + is an emerging standard for JSON canonicalization. + This specification will likely be updated to require such a canonical representation. + Users are cautioned from depending on the + JSON literal lexical representation as an RDF literal, + as the specifics of serialization may change in a future revision of this document.
+ Despite being defined as a set of strings, + this value space is considered distinct from the value space of xsd:string, + in order to avoid side effects with existing specifications. +
+
The lexical-to-value mapping
+
maps any element of the lexical space to the result of +
    +
  1. parsing it into + an internal representation consistent with [ECMASCRIPT] representation + created by using the JSON.parse function as defined in + Section 24.5 The JSON Object of [ECMASCRIPT],
    2. +
  2. then serializing it in the JSON format [RFC8259] + in compliance with the constraints of the value space described above. +
    3. +
+
+
The canonical mapping
+
maps any element of the value space to the identical string in the lexical space.
+
+
+ +

10.3 The i18n Namespace

This section is non-normative.

+

The i18n namespace is used for describing combinations of language tag and base direction in RDF literals. + It is used as an alternative mechanism for describing the [BCP47] language tag and base direction + of RDF literals that would otherwise use the xsd:string or rdf:langString datatypes.

+

Datatypes based on this namespace allow round-tripping of JSON-LD documents using base direction, + although the mechanism is not otherwise standardized.

+

The Deserialize JSON-LD to RDF Algorithm + can be used with the rdfDirection option + set to i18n-datatype to generate RDF literals using the i18n base to create an IRI + encoding the base direction along with optional language tag (normalized to lower case) + from value objects containing @direction by appending to https://www.w3.org/ns/i18n# + the value of @language, if any, followed by an underscore ("_") followed + by the value of @direction.

+ +

For improved interoperability, the language tag is normalized to + lower case when creating the datatype IRI.

+ +

The following example shows two statements with literal values of i18n:ar-EG_rtl, + which encodes the language tag ar-EG and the base direction rtl.

+ 
@prefix ex: <http://example.org/> .
+@prefix i18n: <https://www.w3.org/ns/i18n#> .
+
+# Note that this version preserves the base direction using a non-standard datatype.
+[
+  ex:title "HTML و CSS: تصميم و إنشاء مواقع الويب"^^i18n:ar-eg_rtl;
+  ex:publisher "مكتبة"^^i18n:ar-eg_rtl
+] .
+

See § 4.2.4.1 Base Direction for more details + on using base direction for strings.

+
+ +

10.4 The rdf:CompoundLiteral class and the rdf:language and rdf:direction properties

This section is non-normative.

+

This specification defines the rdf:CompoundLiteral class, which is in the domain + of rdf:language and rdf:direction to be used for describing RDF literal values + containing base direction and a possible language tag to be associated with the + string value of rdf:value on the same subject.

+ +
+
rdf:CompoundLiteral
+
A class representing a compound literal.
+
rdf:language
+
An RDF property. + The range of the property is an rdfs:Literal, whose value MUST be a well-formed [BCP47] language tag. + The domain of the property is rdf:CompoundLiteral.
+
rdf:direction
+
An RDF property. + The range of the property is an rdfs:Literal, whose value MUST be either "ltr" or "rtl". + The domain of the property is rdf:CompoundLiteral.
+
+ +

The Deserialize JSON-LD to RDF Algorithm + can be used with the rdfDirection option + set to compound-literal to generate RDF literals using these properties to + describe the base direction and optional language tag (normalized to lower case) + from value objects containing @direction and optionally @language.

+ +

For improved interoperability, the language tag is normalized to + lower case when creating the datatype IRI.

+ +

The following example shows two statements with compound literals + representing strings with the language tag ar-EG and base direction rtl.

+ 
@prefix ex: <http://example.org/> .
+
+# Note that this version preserves the base direction using a bnode structure.
+[
+  ex:title [
+    rdf:value "HTML و CSS: تصميم و إنشاء مواقع الويب",
+    rdf:language "ar-eg",
+    rdf:direction "rtl"
+  ];
+  ex:publisher [
+    rdf:value "مكتبة",
+    rdf:language "ar-eg",
+    rdf:direction "rtl"
+  ]
+] .
+

See § 4.2.4.1 Base Direction for more details + on using base direction for strings.

+
+
+ +
+

11. Security Considerations

+

See, Security Considerations in § C. IANA Considerations.

+ +
Note

Future versions of this specification + may incorporate subresource integrity [SRI] as a means of ensuring that cached and retrieved + content matches data retrieved from remote servers; see issue 86.

+
+ +
+

12. Privacy Considerations

+

The retrieval of external contexts can expose the operation of a JSON-LD processor, + allow intermediate nodes to fingerprint the client application through introspection of retrieved resources + (see [fingerprinting-guidance]), + and provide an opportunity for a man-in-the-middle attack. + To protect against this, publishers should consider caching remote contexts for future use, + or use the documentLoader + to maintain a local version of such contexts.

+
+ +
+

13. Internationalization Considerations

+

As JSON-LD uses the RDF data model, it is restricted by design in its ability to + properly record JSON-LD Values which are strings with left-to-right or right-to-left direction indicators. + Both JSON-LD and RDF provide a mechanism for specifying the language associated with + a string (language-tagged string), but do not provide a means of indicating + the base direction of the string.

+ +

Unicode provides a mechanism for signaling direction within a string + (see Unicode Bidirectional Algorithm [UAX9]), + however, when a string has an overall base direction which cannot be determined by the + beginning of the string, an external indicator is required, + such as the [HTML] dir attribute, + which currently has no counterpart for RDF literals.

+ +

The issue of properly representing base direction in RDF is not something that + this Working Group can handle, as it is a limitation or the core RDF data model. + This Working Group expects that a future RDF Working Group will consider the matter + and add the ability to specify the base direction of language-tagged strings.

+ +

Until a more comprehensive solution can be addressed in a future version of this + specification, publishers should consider this issue when representing strings + where the base direction of the string cannot otherwise be correctly inferred + based on the content of the string. + See [string-meta] for a discussion best practices for + identifying language and base direction for strings used on the Web.

+
+ +

A. Image Descriptions

This section is non-normative.

+

A.1 Linked Data Dataset

This section is non-normative.

+

This section describes the Linked Data Dataset figure in § 8. Data Model.

+

The image consists of three dashed boxes, each describing a different + linked data graph. Each box consists of shapes linked with arrows describing + the linked data relationships.

+

The first box is titled "default graph: <no name>" describes two + resources: http://example.com/people/alice and http://example.com/people/bob + (denoting "Alice" and "Bob" respectively), which are + connected by an arrow labeled schema:knows which describes + the knows relationship between the two resources. Additionally, the "Alice" resource is related + to three different literals:

+
+
Alice
+
an RDF literal with no datatype or language.
+
weiblich | de
+
an language-tagged string with the value "weiblich" and language tag "de".
+
female | en
+
an language-tagged string with the value "female" and language tag "en".
+
+ +

The second and third boxes describe two named graphs, with the graph names + "http://example.com/graphs/1" and "http://example.com/graphs/1", respectively.

+

The second box consists of two resources: + http://example.com/people/alice and http://example.com/people/bob + related by the schema:parent relationship, and names the + http://example.com/people/bob "Bob".

+

The third box consists of two resources, one + named http://example.com/people/bob and the other unnamed. + The two resources related to each other using schema:sibling relationship + with the second named "Mary".

+
+
+ +
+

B. Relationship to Other Linked Data Formats

This section is non-normative.

+ +

The JSON-LD examples below demonstrate how JSON-LD can be used to + express semantic data marked up in other linked data formats such as Turtle, + RDFa, and Microdata. These sections are merely provided as + evidence that JSON-LD is very flexible in what it can express across different + Linked Data approaches.

+ +
+

B.1 Turtle

This section is non-normative.

+ +

The following are examples of transforming RDF expressed in [Turtle] + into JSON-LD.

+ +
+

B.1.1 Prefix definitions

+ +

The JSON-LD context has direct equivalents for the Turtle + @prefix declaration:

+ +
+
+ Example 154: A set of statements serialized in Turtle + 
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://manu.sporny.org/about#manu> a foaf:Person;
+  foaf:name "Manu Sporny";
+  foaf:homepage <http://manu.sporny.org/> .
+
+ +
+
+ Example 155: The same set of statements serialized in JSON-LD + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/"
+  },
+  "@id": "http://manu.sporny.org/about#manu",
+  "@type": "foaf:Person",
+  "foaf:name": "Manu Sporny",
+  "foaf:homepage": { "@id": "http://manu.sporny.org/" }
+}
+
+
+ +
+

B.1.2 Embedding

+ +

Both [Turtle] and JSON-LD allow embedding, although [Turtle] only allows embedding of + blank nodes.

+ +
+
+ Example 156: Embedding in Turtle + 
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://manu.sporny.org/about#manu>
+  a foaf:Person;
+  foaf:name "Manu Sporny";
+  foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .
+
+ +
+
+ Example 157: Same embedding example in JSON-LD + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/"
+  },
+  "@id": "http://manu.sporny.org/about#manu",
+  "@type": "foaf:Person",
+  "foaf:name": "Manu Sporny",
+  "foaf:knows": {
+    "@type": "foaf:Person",
+    "foaf:name": "Gregg Kellogg"
+  }
+}
+
+
+ +
+

B.1.3 Conversion of native data types

+ +

In JSON-LD numbers and boolean values are native data types. While [Turtle] + has a shorthand syntax to express such values, RDF's abstract syntax requires + that numbers and boolean values are represented as typed literals. Thus, + to allow full round-tripping, the JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API] + defines conversion rules between JSON-LD's native data types and RDF's + counterparts. Numbers without fractions are + converted to xsd:integer-typed literals, numbers with fractions + to xsd:double-typed literals and the two boolean values + true and false to a xsd:boolean-typed + literal. All typed literals are in canonical lexical form.

+ +
+
+ Example 158: JSON-LD using native data types for numbers and boolean values + 
{
+  "@context": {
+    "ex": "http://example.com/vocab#"
+  },
+  "@id": "http://example.com/",
+  "ex:numbers": [ 14, 2.78 ],
+  "ex:booleans": [ true, false ]
+}
+
+ +
+
+ Example 159: Same example in Turtle using typed literals + 
@prefix ex: <http://example.com/vocab#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+<http://example.com/>
+  ex:numbers "14"^^xsd:integer, "2.78E0"^^xsd:double ;
+  ex:booleans "true"^^xsd:boolean, "false"^^xsd:boolean .
+
+ +
Note
Note that this interpretation differs from [Turtle], + in which the literal 2.78 translates to an xsd:decimal. + The rationale is that most JSON tools parse numbers with fractions as + floating point numbers, + so xsd:double is the most appropriate datatype to render them back in RDF. +
+ +
+ +
+

B.1.4 Lists

+

Both JSON-LD and [Turtle] can represent sequential lists of values.

+ +
+
+ Example 160: A list of values in Turtle + 
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://example.org/people#joebob> a foaf:Person;
+  foaf:name "Joe Bob";
+  foaf:nick ( "joe" "bob" "jaybee" ) .
+
+ +
+
+ Example 161: Same example with a list of values in JSON-LD + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/"
+  },
+  "@id": "http://example.org/people#joebob",
+  "@type": "foaf:Person",
+  "foaf:name": "Joe Bob",
+  "foaf:nick": {
+    "@list": [ "joe", "bob", "jaybee" ]
+  }
+}
+
+
+
+ +
+

B.2 RDFa

This section is non-normative.

+ +

The following example describes three people with their respective names and + homepages in RDFa [RDFA-CORE].

+ +
+
+ Example 162: RDFa fragment that describes three people + 
<div prefix="foaf: http://xmlns.com/foaf/0.1/">
+   <ul>
+      <li typeof="foaf:Person">
+        <a property="foaf:homepage" href="http://example.com/bob/">
+          <span property="foaf:name">Bob</span>
+        </a>
+      </li>
+      <li typeof="foaf:Person">
+        <a property="foaf:homepage" href="http://example.com/eve/">
+         <span property="foaf:name">Eve</span>
+        </a>
+      </li>
+      <li typeof="foaf:Person">
+        <a property="foaf:homepage" href="http://example.com/manu/">
+          <span property="foaf:name">Manu</span>
+        </a>
+      </li>
+   </ul>
+</div>
+
+ +

An example JSON-LD implementation using a single context is + described below.

+ +
+
+ Example 163: Same description in JSON-LD (context shared among node objects) + 
{
+  "@context": {
+    "foaf": "http://xmlns.com/foaf/0.1/",
+    "foaf:homepage": {"@type": "@id"}
+  },
+  "@graph": [
+    {
+      "@type": "foaf:Person",
+      "foaf:homepage": "http://example.com/bob/",
+      "foaf:name": "Bob"
+    }, {
+      "@type": "foaf:Person",
+      "foaf:homepage": "http://example.com/eve/",
+      "foaf:name": "Eve"
+    }, {
+      "@type": "foaf:Person",
+      "foaf:homepage": "http://example.com/manu/",
+      "foaf:name": "Manu"
+    }
+  ]
+}
+
+
+ +
+

B.3 Microdata

This section is non-normative.

+ +

The HTML Microdata [MICRODATA] example below expresses book information as + a Microdata Work item.

+ +
+
+ Example 164: HTML that describes a book using microdata + 
<dl itemscope
+    itemtype="http://purl.org/vocab/frbr/core#Work"
+    itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
+ <dt>Title</dt>
+ <dd><cite itemprop="http://purl.org/dc/elements/1.1/title">Just a Geek</cite></dd>
+ <dt>By</dt>
+ <dd><span itemprop="http://purl.org/dc/elements/1.1/creator">Wil Wheaton</span></dd>
+ <dt>Format</dt>
+ <dd itemprop="http://purl.org/vocab/frbr/core#realization"
+     itemscope
+     itemtype="http://purl.org/vocab/frbr/core#Expression"
+     itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
+  <link itemprop="http://purl.org/dc/elements/1.1/type" href="http://purl.oreilly.com/product-types/BOOK">
+  Print
+ </dd>
+ <dd itemprop="http://purl.org/vocab/frbr/core#realization"
+     itemscope
+     itemtype="http://purl.org/vocab/frbr/core#Expression"
+     itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
+  <link itemprop="http://purl.org/dc/elements/1.1/type" href="http://purl.oreilly.com/product-types/EBOOK">
+  Ebook
+ </dd>
+</dl>
+
+ +

Note that the JSON-LD representation of the Microdata information stays + true to the desires of the Microdata community to avoid contexts and + instead refer to items by their full IRI.

+ +
+
+ Example 165: Same book description in JSON-LD (avoiding contexts) + 
[
+  {
+    "@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",
+    "@type": "http://purl.org/vocab/frbr/core#Work",
+    "http://purl.org/dc/elements/1.1/title": "Just a Geek",
+    "http://purl.org/dc/elements/1.1/creator": "Wil Wheaton",
+    "http://purl.org/vocab/frbr/core#realization":
+    [
+      {"@id": "http://purl.oreilly.com/products/9780596007683.BOOK"},
+      {"@id": "http://purl.oreilly.com/products/9780596802189.EBOOK"}
+    ]
+  }, {
+    "@id": "http://purl.oreilly.com/products/9780596007683.BOOK",
+    "@type": "http://purl.org/vocab/frbr/core#Expression",
+    "http://purl.org/dc/elements/1.1/type": {"@id": "http://purl.oreilly.com/product-types/BOOK"}
+  }, {
+    "@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",
+    "@type": "http://purl.org/vocab/frbr/core#Expression",
+    "http://purl.org/dc/elements/1.1/type": {"@id": "http://purl.oreilly.com/product-types/EBOOK"}
+  }
+]
+
+
+
+ +
+

C. IANA Considerations

+ +

This section has been submitted to the Internet Engineering Steering + Group (IESG) for review, approval, and registration with IANA.

+ +

application/ld+json

+
+
Type name:
+
application
+
Subtype name:
+
ld+json
+
Required parameters:
+
N/A
+
Optional parameters:
+
+
+
profile
+
+

A non-empty list of space-separated URIs identifying specific + constraints or conventions that apply to a JSON-LD document according to [RFC6906]. + A profile does not change the semantics of the resource representation + when processed without profile knowledge, so that clients both with + and without knowledge of a profiled resource can safely use the same + representation. The profile parameter MAY be used by + clients to express their preferences in the content negotiation process. + If the profile parameter is given, a server SHOULD return a document that + honors the profiles in the list which it recognizes, + and MUST ignore the profiles in the list which it does not recognize. + It is RECOMMENDED that profile URIs are dereferenceable and provide + useful documentation at that URI. For more information and background + please refer to [RFC6906].

+

This specification defines six values for the profile parameter.

+
+
http://www.w3.org/ns/json-ld#expanded
+
To request or specify expanded JSON-LD document form.
+
http://www.w3.org/ns/json-ld#compacted
+
To request or specify compacted JSON-LD document form.
+
http://www.w3.org/ns/json-ld#context
+
To request or specify a JSON-LD context document.
+
http://www.w3.org/ns/json-ld#flattened
+
To request or specify flattened JSON-LD document form.
+
http://www.w3.org/ns/json-ld#frame
+
To request or specify a JSON-LD frame document.
+
http://www.w3.org/ns/json-ld#framed
+
To request or specify framed JSON-LD document form.
+
+

All other URIs starting with http://www.w3.org/ns/json-ld + are reserved for future use by JSON-LD specifications.

+ +

Other specifications may publish additional profile parameter + URIs with their own defined semantics. + This includes the ability to associate a file extension with a profile parameter.

+

+ When used as a media type parameter [RFC4288] + in an HTTP Accept header [RFC7231], + the value of the profile parameter MUST be enclosed in quotes (") if it contains + special characters such as whitespace, which is required when multiple profile URIs are combined.

+

When processing the "profile" media type parameter, it is important to + note that its value contains one or more URIs and not IRIs. In some cases + it might therefore be necessary to convert between IRIs and URIs as specified in + section 3 Relationship between IRIs and URIs + of [RFC3987].

+
+
+
+
Encoding considerations:
+
See RFC 8259, section 11.
+
Security considerations:
+
See RFC 8259, section 12 [RFC8259] +

Since JSON-LD is intended to be a pure data exchange format for + directed graphs, the serialization SHOULD NOT be passed through a + code execution mechanism such as JavaScript's eval() + function to be parsed. An (invalid) document may contain code that, + when executed, could lead to unexpected side effects compromising + the security of a system.

+

When processing JSON-LD documents, links to remote contexts and frames are + typically followed automatically, resulting in the transfer of files + without the explicit request of the user for each one. If remote + contexts are served by third parties, it may allow them to gather + usage patterns or similar information leading to privacy concerns. + Specific implementations, such as the API defined in the + JSON-LD 1.1 Processing Algorithms and API specification [JSON-LD11-API], + may provide fine-grained mechanisms to control this behavior.

+

JSON-LD contexts that are loaded from the Web over non-secure connections, + such as HTTP, run the risk of being altered by an attacker such that + they may modify the JSON-LD active context in a way that + could compromise security. It is advised that any application that + depends on a remote context for mission critical purposes vet and + cache the remote context before allowing the system to use it.

+

Given that JSON-LD allows the substitution of long IRIs with short terms, + JSON-LD documents may expand considerably when processed and, in the worst case, + the resulting data might consume all of the recipient's resources. Applications + should treat any data with due skepticism.

+

As JSON-LD places no limits on the IRI schemes that may be used, + and vocabulary-relative IRIs use string concatenation rather than + IRI resolution, it is possible to construct IRIs that may be + used maliciously, if dereferenced.

+
+
Interoperability considerations:
+
Not Applicable
+
Published specification:
+
http://www.w3.org/TR/json-ld
+
Applications that use this media type:
+
Any programming environment that requires the exchange of + directed graphs. Implementations of JSON-LD have been created for + JavaScript, Python, Ruby, PHP, and C++. +
+
Additional information:
+
+
+
Magic number(s):
+
Not Applicable
+
File extension(s):
+
.jsonld
+
Macintosh file type code(s):
+
TEXT
+
+
+
Person & email address to contact for further information:
+
Ivan Herman <ivan@w3.org>
+
Intended usage:
+
Common
+
Restrictions on usage:
+
N/A
+
Author(s):
+
Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström
+
Change controller:
+
W3C
+
+ +

Fragment identifiers used with application/ld+json + are treated as in RDF syntaxes, as per + RDF 1.1 Concepts and Abstract Syntax + [RDF11-CONCEPTS].

+ +

This registration is an update to the original definition + for application/ld+json + in [JSON-LD10].

+ +
+

C.1 Examples

This section is non-normative.

+

The following examples illustrate different ways in which the profile parameter may be used + to describe different acceptable responses.

+ +
+
+ Example 166: HTTP Request with profile requesting an expanded document + 
GET /ordinary-json-document.json HTTP/1.1
+Host: example.com
+Accept: application/ld+json;profile=http://www.w3.org/ns/json-ld#expanded
+
+

Requests the server to return the requested resource as JSON-LD + in expanded document form.

+ +
+
+ Example 167: HTTP Request with profile requesting a compacted document + 
GET /ordinary-json-document.json HTTP/1.1
+Host: example.com
+Accept: application/ld+json;profile=http://www.w3.org/ns/json-ld#compacted
+
+

Requests the server to return the requested resource as JSON-LD + in compacted document form. + As no explicit context resource is specified, the server compacts + using an application-specific default context.

+ +
+
+ Example 168: HTTP Request with profile requesting a compacted document with a reference to a compaction context + 
GET /ordinary-json-document.json HTTP/1.1
+Host: example.com
+Accept: application/ld+json;profile="http://www.w3.org/ns/json-ld#flattened http://www.w3.org/ns/json-ld#compacted"
+
+

Requests the server to return the requested resource as JSON-LD + in both compacted document form + and flattened document form. + Note that as whitespace is used to separate the two URIs, they + are enclosed in double quotes (").

+
+
+ +
+

D. Open Issues

This section is non-normative.

+

The following is a list of issues open at the time of publication.

+
Issue 108: Consider context by reference with metadata defer-future-versionprivacy-trackersecurity-tracker

Consider context by reference with metadata.

+
Issue 191: Compact IRI expansion support for non-trivial prefix term definitions defer-future-versionspec:enhancement

Compact IRI expansion support for non-trivial prefix term definitions.

+
Issue 280: language-maps don't allow separate base direction defer-future-version

Language-maps don't allow separate base direction.

+
Issue 328: @default in @context in JSON-LD core syntax defer-future-version

@default in @context in JSON-LD core syntax.

+
Issue 329: Suggestion about `@prefix` defer-future-version

Suggestion about @prefix.

+
Issue 335: Type Coercion / Node Conversion: @coerce keyword or similar defer-future-version

Type Coercion / Node Conversion: @coerce keyword or similar.

+
+ +
+

E. Changes since 1.0 Recommendation of 16 January 2014

This section is non-normative.

+ +

Additionally, see § F. Changes since JSON-LD Community Group Final Report.

+
+ +
+

F. Changes since JSON-LD Community Group Final Report

This section is non-normative.

+
    +
  • Lists may now have items which are themselves lists.
    • +
  • Values of @type, or an alias of @type, may now have their @container set to @set + to ensure that @type entries are always represented as an array. This + also allows a term to be defined for @type, where the value MUST be a map + with @container set to @set.
    • +
  • The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, as is the support for generalized RDF Datasets.
    • +
  • The vocabulary mapping can be a relative IRI reference, which is evaluated + either against an existing default vocabulary, or against the document base. + This allows vocabulary-relative IRIs, such as the + keys of node objects, are expanded or compacted relative + to the document base. + (See Security Considerations in § C. IANA Considerations + for a discussion on how string vocabulary-relative IRI resolution via concatenation. + )
    • +
  • Added support for "@type": "@none" in a term definition to prevent value compaction. + Define the rdf:JSON datatype.
    • +
  • Term definitions with keys which are of the form of an IRI reference or a compact IRI MUST NOT + expand to an IRI other than the expansion of the key itself.
    • +
  • A frame may also be located within an HTML document, identified + using type application/ld+json;profile=http://www.w3.org/ns/json-ld#frame.
    • +
  • Term definitions can now be protected, + to limit the ability of other contexts to override them.
    • +
  • A context defined in an expanded term definition may also be used for values + of @type, which defines a context to use for node objects including the associated type.
    • +
  • By default, all contexts are propagated when traversing node objects, other than + type-scoped contexts. This can be controlled using the @propagate + entry in a local context.
    • +
  • A context may contain an @import entry used to reference a remote context + within a context, allowing JSON-LD 1.1 features to be added to contexts originally + authored for JSON-LD 1.0.
    • +
  • A node object may include an included block, + which is used to contain a set of node objects which are treated + exactly as if they were node objects defined in an array including the containing + node object. + This allows the use of the object form of a JSON-LD document when there is more + than one node object being defined, and where those node objects + are not embedded as values of the containing node object.
    • +
  • The alternate link relation can be used to supply an alternate location for + retrieving a JSON-LD document when the returned document is not JSON.
    • +
  • Value objects, and associated context and term definitions have been updated to + support @direction for setting the base direction of strings.
    • +
  • The processing mode is now implicitly json-ld-1.1, unless set + explicitly to json-ld-1.0.
    • +
  • Improve notation using IRI, IRI reference, and relative IRI reference.
    • + +
  • Warn about forward-compatibility issues for terms of the form ("@"1*ALPHA).
    • +
  • When creating an i18n datatype or rdf:CompoundLiteral, language tags are + normalized to lower case to improve interoperability between implementations.
    • +
+
+
+

G. Changes since Candidate Release of 12 December 2019

This section is non-normative.

+ +
+
+

H. Changes since Proposed Recommendation Release of 7 May 2020

This section is non-normative.

+
    +
  • Removed remaining "at-risk" notes.
    • +
  • Update bibliographic reference for JCS to [RFC8785].
    • +
  • Fixed typo in § 9.3 Frame Objects, + which was unintentionally diverging from the normative description of the @embed keyword in JSON-LD 1.1 Framing. + This is in response to Issue 358.
    • +
+
+ +
+

I. Acknowledgements

This section is non-normative.

+

+ The editors would like to specially thank the following individuals for making significant + contributions to the authoring and editing of this specification: +

+ +
    +
  • Timothy Cole (University of Illinois at Urbana-Champaign)
    • +
  • Gregory Todd Williams (J. Paul Getty Trust)
    • +
  • Ivan Herman (W3C Staff)
    • +
  • Jeff Mixter (OCLC (Online Computer Library Center, Inc.))
    • +
  • David Lehn (Digital Bazaar)
    • +
  • David Newbury (J. Paul Getty Trust)
    • +
  • Robert Sanderson (J. Paul Getty Trust, chair)
    • +
  • Harold Solbrig (Johns Hopkins Institute for Clinical and Translational Research)
    • +
  • Simon Steyskal (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
    • +
  • A Soroka (Apache Software Foundation)
    • +
  • Ruben Taelman (Imec vzw)
    • +
  • Benjamin Young (Wiley, chair)
    • +
+ +

Additionally, the following people were members of the Working Group at the time of publication:

+ +
    +
  • Steve Blackmon (Apache Software Foundation)
    • +
  • Dan Brickley (Google, Inc.)
    • +
  • Newton Calegari (NIC.br - Brazilian Network Information Center)
    • +
  • Victor Charpenay (Siemens AG)
    • +
  • Sebastian Käbisch (Siemens AG)
    • +
  • Axel Polleres (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
    • +
  • Leonard Rosenthol (Adobe)
    • +
  • Jean-Yves ROSSI (CANTON CONSULTING)
    • +
  • Antoine Roulin (CANTON CONSULTING)
    • +
  • Manu Sporny (Digital Bazaar)
    • +
  • Clément Warnier de Wailly (CANTON CONSULTING)
    • +
+ +

+ A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons: Chris Webber, David Wood, Drummond Reed, Eleanor Joslin, Fabien Gandon, Herm Fisher, Jamie Pitts, Kim Hamilton Duffy, Niklas Lindström, Paolo Ciccarese, Paul Frazze, Paul Warren, Reto Gmür, Rob Trainer, Ted Thibodeau Jr., and Victor Charpenay. +

+ +
+ + + + +

J. References

+

J.1 + Normative references +

+
+
[BCP47]
Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47
[DOM]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[IANA-URI-SCHEMES]
Uniform Resource Identifier (URI) Schemes. IANA. URL: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml
[JSON]
The application/json Media Type for JavaScript Object Notation (JSON). D. Crockford. IETF. July 2006. Informational. URL: https://tools.ietf.org/html/rfc4627
[JSON-LD10]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Marcus Langhaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/2014/REC-json-ld-20140116/
[JSON-LD11-API]
JSON-LD 1.1 Processing Algorithms and API. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11-api/
[JSON-LD11-FRAMING]
JSON-LD 1.1 Framing. Dave Longley; Gregg Kellogg; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11-framing/
[RDF-SCHEMA]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
[RDF11-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[RDF11-MT]
RDF 1.1 Semantics. Patrick Hayes; Peter Patel-Schneider. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-mt/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[RFC3987]
Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc3987
[RFC4288]
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin. IETF. December 2005. Best Current Practice. URL: https://tools.ietf.org/html/rfc4288
[RFC5234]
Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://tools.ietf.org/html/rfc5234
[RFC6839]
Additional Media Type Structured Syntax Suffixes. T. Hansen; A. Melnikov. IETF. January 2013. Informational. URL: https://tools.ietf.org/html/rfc6839
[RFC6906]
The 'profile' Link Relation Type. E. Wilde. IETF. March 2013. Informational. URL: https://tools.ietf.org/html/rfc6906
[RFC7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed. June 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7231
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259
[RFC8288]
Web Linking. M. Nottingham. October 2017. Proposed Standard. URL: https://tools.ietf.org/html/rfc8288
[UAX9]
Unicode Bidirectional Algorithm. Mark Davis; Aharon Lanin; Andrew Glass. Unicode Consortium. 12 February 2020. Unicode Standard Annex #9. URL: https://www.unicode.org/reports/tr9/tr9-42.html
[UNICODE]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
+
+

J.2 + Informative references +

+
+
[fingerprinting-guidance]
Mitigating Browser Fingerprinting in Web Specifications. Nick Doty. W3C. 28 March 2019. W3C Note. URL: https://www.w3.org/TR/fingerprinting-guidance/
[INFRA]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[JSON.API]
JSON API. Steve Klabnik; Yehuda Katz; Dan Gebhardt; Tyler Kellen; Ethan Resnick. 29 May 2015. unofficial. URL: https://jsonapi.org/format/
[ld-glossary]
Linked Data Glossary. Bernadette Hyland; Ghislain Auguste Atemezing; Michael Pendleton; Biplav Srivastava. W3C. 27 June 2013. W3C Note. URL: https://www.w3.org/TR/ld-glossary/
[LINKED-DATA]
Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html
[MICRODATA]
HTML Microdata. Charles 'chaals' (McCathie) Nevile; Dan Brickley; Ian Hickson. W3C. 26 April 2018. W3C Working Draft. URL: https://www.w3.org/TR/microdata/
[RDFA-CORE]
RDFa Core 1.1 - Third Edition. Ben Adida; Mark Birbeck; Shane McCarron; Ivan Herman et al. W3C. 17 March 2015. W3C Recommendation. URL: https://www.w3.org/TR/rdfa-core/
[rfc4122]
A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc4122
[RFC7049]
Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. October 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7049
[RFC7946]
The GeoJSON Format. H. Butler; M. Daly; A. Doyle; S. Gillies; S. Hagen; T. Schaub. IETF. August 2016. Proposed Standard. URL: https://tools.ietf.org/html/rfc7946
[RFC8785]
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman. Network Working Group. June 2020. Informational. URL: https://www.rfc-editor.org/rfc/rfc8785
[SPARQL11-OVERVIEW]
SPARQL 1.1 Overview. The W3C SPARQL Working Group. W3C. 21 March 2013. W3C Recommendation. URL: https://www.w3.org/TR/sparql11-overview/
[SRI]
Subresource Integrity. Devdatta Akhawe; Frederik Braun; Francois Marier; Joel Weinberger. W3C. 23 June 2016. W3C Recommendation. URL: https://www.w3.org/TR/SRI/
[string-meta]
Strings on the Web: Language and Direction Metadata. Addison Phillips; Richard Ishida. W3C. 11 June 2019. W3C Working Draft. URL: https://www.w3.org/TR/string-meta/
[TriG]
RDF 1.1 TriG. Gavin Carothers; Andy Seaborne. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/trig/
[Turtle]
RDF 1.1 Turtle. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/
[URN]
URN Syntax. R. Moats. IETF. May 1997. Proposed Standard. URL: https://tools.ietf.org/html/rfc2141
[WEBIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[YAML]
YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html
+
\ No newline at end of file diff --git a/docs/standards/references/n-quads.html b/docs/standards/references/n-quads.html new file mode 100644 index 0000000..a45b8ff --- /dev/null +++ b/docs/standards/references/n-quads.html @@ -0,0 +1,796 @@ + + + + RDF 1.1 N-Quads + + + + + + + + + +

Abstract

+ N-Quads is a line-based, plain text format for encoding an RDF dataset. +

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

This document is part of the RDF 1.1 document suit. +The N-Quads format is a line-based RDF syntax with a similar flavor as N-Triples +[N-TRIPLES]. The main distinction is that N-Quads allows encoding +multiple graphs.

+ +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ +

+ Please see the Working Group's implementation + report. +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + +
+ + +

1. Introduction

+ +

+ This document defines N-Quads, an easy to parse, line-based, + concrete syntax for + RDF Datasets + [RDF11-CONCEPTS]. +

+ +

N-quads statements are a sequence of RDF terms representing the subject, predicate, object and graph label of an RDF Triple and the graph it is part of in a dataset. These may be separated by white space (spaces #x20 or tabs #x9). This sequence is terminated by a '.' and a new line (optional at the end of a document). +

+ +
Example 1
+ +
+ +
+ + +

2. N-Quads Language

+
+

2.1 Simple Statements

+

The simplest statement is a sequence of (subject, predicate, object) terms forming an RDF triple and an optional blank node label or IRI labeling what graph in a dataset the triple belongs to, all are separated by whitespace and terminated by '.' after each statement.

+
Example 2
+

The graph label IRI can be omitted, in which case the triples are considered part of the default graph of the RDF dataset.

+

+
+

2.2 IRIs

+ +

+ IRIs may be written only as absolute IRIs. + IRIs are enclosed in '<' and '>' and may contain numeric escape sequences (described below). For example <http://example.org/#green-goblin>. +

+
+
+

2.3 RDF Literals

+ +

Literals are used to identify values such as strings, numbers, dates.

+ + +

+ Literals (Grammar production Literal) have a lexical form followed by a language tag, a datatype IRI, or neither. + The representation of the lexical form consists of an initial delimiter " (U+0022), a sequence of permitted characters or numeric escape sequence or string escape sequence, and a final delimiter. Literals may not contain the characters ", LF, or CR. In addition '\' (U+005C) may not appear in any quoted literal except as part of an escape sequence. + The corresponding RDF lexical form is the characters between the delimiters, after processing any escape sequences. + If present, the language tag is preceded by a '@' (U+0040). + If there is no language tag, there may be a datatype IRI, preceded by '^^' (U+005E U+005E). If there is no datatype IRI and no language tag, the datatype is xsd:string. +

+
+
+

2.4 RDF Blank Nodes

+

+ RDF blank nodes in N-Quads are expressed as _: followed by a blank node label which is a series of name characters. + The characters in the label are built upon PN_CHARS_BASE, liberalized as follows: +

+
    +
  • The characters _ and digits may appear anywhere in a blank node label.
    • +
  • The character . may appear anywhere except the first or last character.
    • +
  • The characters -, U+00B7, U+0300 to U+036F and U+203F to U+2040 are permitted anywhere except the first character.
    • +
+

+ A fresh RDF blank node is allocated for each unique blank node label in a document. + Repeated use of the same blank node label identifies the same RDF blank node. +

+
Example 3
+
+ +
+ +
+ +

3. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

+ The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, + and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. +

+ +

This specification defines conformance criteria for:

+
    +
  • N-Quads documents +
  • N-Quads parsers +
+

A conforming N-Quads document is a Unicode string that conforms to the grammar and additional constraints defined in section 4. Grammar, starting with the nquadsDoc production. An N-Quad document serializes an RDF dataset.

+ +
Note

N-Quads documents do not provide a way of serializing empty graphs that may be part of an RDF dataset.

+ +

A conforming N-Quads parser is a system capable of reading N-Quads documents on behalf of an application. It makes the serialized RDF graph, as defined in section 5. Parsing, available to the application, usually through some form of API.

+ +

The IRI that identifies the N-Quads language is: http://www.w3.org/ns/formats/N-Quads

+ +
+

3.1 Media Type and Content Encoding

+ +

The media type of N-Quads is application/n-quads. + The content encoding of N-Quads is always UTF-8. + See N-Quads Media Type for the media type + registration form. +

+ +
+

3.1.1 Other Media Types

+

The original specification, + N-Quads: Extending N-Triples with Context, + proposed the use of media type text/x-nquads with an encoding + using 7-bit US-ASCII.

+
+ + +
+
+ +
+ + +

4. Grammar

+

An N-Quads document is a Unicode[UNICODE] character string encoded in UTF-8. + Unicode code points only in the range U+0 to U+10FFFF inclusive are allowed.

+

White space (tab U+0009 or space U+0020) is used to separate two terminals which would otherwise be (mis-)recognized as one terminal. White space is significant in the production STRING_LITERAL_QUOTE.

+

Comments in N-Quads take the form of '#', outside an IRIREF or STRING_LITERAL_QUOTE, and continue to the end of line (EOL) or end of file if there is no end of line after the comment marker. Comments are treated as white space.

+

The EBNF used here is defined in XML 1.0 + [EBNF-NOTATION].

+

Escape sequence rules are the same as Turtle + [TURTLE]. However, as only the STRING_LITERAL_QUOTE production is allowed new lines in literals MUST be escaped.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1]nquadsDoc::=statement? (EOL statement)* EOL?
[2]statement::=subject predicate object graphLabel? '.'
[3]subject::=IRIREF | BLANK_NODE_LABEL
[4]predicate::=IRIREF
[5]object::=IRIREF | BLANK_NODE_LABEL | literal
[6]graphLabel::=IRIREF | BLANK_NODE_LABEL
[7]literal::=STRING_LITERAL_QUOTE ('^^' IRIREF | LANGTAG)?

Productions for terminals

[144s]LANGTAG::='@' [a-zA-Z]+ ('-' [a-zA-Z0-9]+)*
[8]EOL::=[#xD#xA]+
[10]IRIREF::='<' ([^#x00-#x20<>"{}|^`\] | UCHAR)* '>'
[11]STRING_LITERAL_QUOTE::='"' ([^#x22#x5C#xA#xD] | ECHAR | UCHAR)* '"'
[141s]BLANK_NODE_LABEL::='_:' (PN_CHARS_U | [0-9]) ((PN_CHARS | '.')* PN_CHARS)?
[12]UCHAR::='\u' HEX HEX HEX HEX | '\U' HEX HEX HEX HEX HEX HEX HEX HEX
[153s]ECHAR::='\' [tbnrf"'\]
[157s]PN_CHARS_BASE::=[A-Z] | [a-z] | [#x00C0-#x00D6] | [#x00D8-#x00F6] | [#x00F8-#x02FF] | [#x0370-#x037D] | [#x037F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[158s]PN_CHARS_U::=PN_CHARS_BASE | '_' | ':'
[160s]PN_CHARS::=PN_CHARS_U | '-' | [0-9] | #x00B7 | [#x0300-#x036F] | [#x203F-#x2040]
[162s]HEX::=[0-9] | [A-F] | [a-f]
+
+
+
+ + +

5. Parsing

+

Parsing N-Quads requires a state of one item:

+
    +
  • Map[string -> blank node] bnodeLabels — A mapping from string to blank node.
    • +
+ +
+

5.1 RDF Term Constructors

+

This table maps productions and lexical tokens to RDF terms or components of RDF terms listed in section 5. Parsing:

+ + + + + + + + + + + +
productiontypeprocedure
IRIREF IRI The characters between "<" and ">" are taken, with the escape sequences unescaped, to form the unicode string of the IRI.
STRING_LITERAL_QUOTE lexical formThe characters between the outermost '"'s are taken, with escape sequences unescaped, to form the unicode string of a lexical form.
LANGTAG language tagThe characters following the @ form the unicode string of the language tag.
literal literal The literal has a lexical form of the first rule argument, STRING_LITERAL_QUOTE, and either a language tag of LANGTAG or a datatype IRI of iri, depending on which rule matched the input. If the LANGTAG rule matched, the datatype is rdf:langString and the language tag is LANGTAG. If neither a language tag nor a datatype IRI is provided, the literal has a datatype of xsd:string.
BLANK_NODE_LABEL blank node The string matching the second argument, PN_LOCAL, is a key in bnodeLabels. If there is no corresponding blank node in the map, one is allocated.
+
+
+

5.2 RDF Dataset Construction

+

An N-Quads document defines an RDF dataset composed of RDF graphs composed of a set of RDF triples. The statement production produces a triple defined by the terms constructed for subject, predicate and object. This RDF triple is added to the graph labeled by the production graphLabel, if no graphLabel is present the triple is added to the RDF datasets default graph.

+
+ + +
+
+ + +

6. Acknowledgements

This section is non-normative.

+

The editor of the RDF 1.1 edition acknowledges valuable + contributions from Gregg Kellogg, Andy Seaborne, Eric + Prud'hommeaux, Dave Beckett, David Robillard, Gregory Williams, + Antoine Zimmermann, Sandro Hawke, Richard Cyganiak, Pat Hayes, + Henry S. Thompson, Bob Ferris, Henry Story, Andreas Harth, Lee + Feigenbaum, Peter Ansell, Evan Patton and David Booth.

+

This specification is a product of extensive deliberations by the + members of the RDF Working Group chaired by Guus Schreiber and David Wood. It draws upon the eariler specification in N-Quads: Extending N-Triples with Context, edited by Richard Cyganiak, Andreas Harth, and Aidan Hogan.

+
+ +
+ + +

A. Change Log

+
+

A.1 Changes between Proposed Recommendation and Recommendation

+
    +
  • Bug in grammar rule [7] concerning language-typed literals fixed.
    • +
  • Link to original N-Quads proposal included.
    • +
+
+
+

A.2 Changes between Candidate Recommendation and Proposed Recommendation

+
    +
  • A normative reference to RDF Concepts was added.
    • +
  • Informative note about text/x-nquads historical media type added.
    • +
+
+
+

A.3 Changes between Last Call Working Draft and Candidate Recommendation

+

No substitutive changes.

+
+
+

A.4 Changes between publication as Note and Last Call Working Draft

+
    +
  • White space rules defined outside of grammar, as in Turtle.
    • +
  • Comment processing defined.
    • +
  • Parsing is defined.
    • +
  • Recommendation track, not a working group Note.
    • +
+
+
+ +
+ + +

B. N-Quads Internet Media Type, File Extension and Macintosh File Type

+
+
Contact:
+
Eric Prud'hommeaux
+
See also:
+ +
How to Register a Media Type for a W3C Specification
+
Internet Media Type registration, consistency of use
TAG Finding 3 June 2002 (Revised 4 September 2002)
+
+

The Internet Media Type / MIME Type for N-Quads is "application/n-quads".

+

It is recommended that N-Quads files have the extension ".nq" (all lowercase) on all platforms.

+ +

It is recommended that N-Quads files stored on Macintosh HFS file systems be given a file type of "TEXT".

+

This information that follows will be submitted to the IESG for review, approval, and registration with IANA.

+
+
Type name:
+
application
+ +
Subtype name:
+
n-quads
+
Required parameters:
+
None
+
Optional parameters:
+
None
+ +
Encoding considerations:
+
The syntax of N-Quads is expressed over code points in Unicode [UNICODE]. The encoding is always UTF-8 [UTF-8].
+
Unicode code points may also be expressed using an \uXXXX (U+0 to U+FFFF) or \UXXXXXXXX syntax (for U+10000 onwards) where X is a hexadecimal digit [0-9A-F]
+
Security considerations:
+
N-Quads is a general-purpose assertion language; applications may evaluate given data to infer more assertions or to dereference IRIs, invoking the security considerations of the scheme for that IRI. Note in particular, the privacy issues in [RFC3023] section 10 for HTTP IRIs. Data obtained from an inaccurate or malicious data source may lead to inaccurate or misleading conclusions, as well as the dereferencing of unintended IRIs. Care must be taken to align the trust in consulted resources with the sensitivity of the intended use of the data; inferences of potential medical treatments would likely require different trust than inferences for trip planning.
+ +
N-Quads is used to express arbitrary application data; security considerations will vary by domain of use. Security tools and protocols applicable to text (e.g. PGP encryption, MD5 sum validation, password-protected compression) may also be used on N-Quads documents. Security/privacy protocols must be imposed which reflect the sensitivity of the embedded information.
+
N-Quads can express data which is presented to the user, for example, RDF Schema labels. Application rendering strings retrieved from untrusted N-Quads documents must ensure that malignant strings may not be used to mislead the reader. The security considerations in the media type registration for XML ([RFC3023] section 10) provide additional guidance around the expression of arbitrary data and markup.
+
N-Quads uses IRIs as term identifiers. Applications interpreting data expressed in N-Quads should address the security issues of + Internationalized Resource Identifiers (IRIs) [RFC3987] Section 8, as well as + Uniform Resource Identifier (URI): Generic Syntax [RFC3986] Section 7.
+ +
Multiple IRIs may have the same appearance. Characters in different scripts may + look similar (a Cyrillic "о" may appear similar to a Latin "o"). A character followed + by combining characters may have the same visual representation as another character + (LATIN SMALL LETTER E followed by COMBINING ACUTE ACCENT has the same visual representation + as LATIN SMALL LETTER E WITH ACUTE). + + + + Any person or application that is writing or interpreting data in Turtle must take care to use the IRI that matches the intended semantics, and avoid IRIs that make look similar. + Further information about matching of similar characters can be found + in Unicode Security + Considerations [UNICODE-SECURITY] and + Internationalized Resource + Identifiers (IRIs) [RFC3987] Section 8. +
+ +
Interoperability considerations:
+
There are no known interoperability issues.
+
Published specification:
+
This specification.
+
Applications which use this media type:
+ +
No widely deployed applications are known to use this media type. It may be used by some web services and clients consuming their data.
+
Additional information:
+
Magic number(s):
+
None.
+
File extension(s):
+
".nq"
+ +
Macintosh file type code(s):
+
"TEXT"
+
Person & email address to contact for further information:
+ +
Eric Prud'hommeaux <eric@w3.org>
+
Intended usage:
+
COMMON
+
Restrictions on usage:
+
None
+
Author/Change controller:
+ +
The N-Quads specification is the product of the RDF WG. The W3C reserves change control over this specifications.
+
+
+ + + +
+ +

C. References

C.1 Normative references

[EBNF-NOTATION]
Tim Bray; Jean Paoli; C. M. Sperberg-McQueen; Eve Maler; François Yergeau. EBNF Notation 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/REC-xml/#sec-notation +
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-concepts/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3023]
M. Murata; S. St.Laurent; D. Kohn. XML Media Types (RFC 3023). January 2001. RFC. URL: http://www.ietf.org/rfc/rfc3023.txt +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[UTF-8]
F. Yergeau. UTF-8, a transformation format of ISO 10646. IETF RFC 3629. November 2003. URL: http://www.ietf.org/rfc/rfc3629.txt +

C.2 Informative references

[N-TRIPLES]
Gavin Carothers, Andy Seabourne. RDF 1.1 N-Triples. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-n-triples-20140225/. The latest edition is available at http://www.w3.org/TR/n-triples/ +
[TURTLE]
Eric Prud'hommeaux, Gavin Carothers. RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-turtle-20140225/. The latest edition is available at http://www.w3.org/TR/turtle/ +
[UNICODE-SECURITY]
Mark Davis; Michel Suignard. Unicode Security Considerations. URL: http://www.unicode.org/reports/tr36/ +
\ No newline at end of file diff --git a/docs/standards/references/n-triples.html b/docs/standards/references/n-triples.html new file mode 100644 index 0000000..f980805 --- /dev/null +++ b/docs/standards/references/n-triples.html @@ -0,0 +1,833 @@ + + + + RDF 1.1 N-Triples + + + + + + + + + +

Abstract

+ N-Triples is a line-based, plain text format for encoding an RDF graph. +

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +This document is part of the RDF 1.1 document suite. +N-Triples was originally defined as a syntax for +the RDF Test Cases [RDF-TESTCASES] document. Due to its popularity +as an exchange format the RDF +Working Group decided to publish an updated +version. + +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ +

+ Please see the Working Group's implementation + report. +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + + + + +
+ + +

1. Introduction

+

+ This document defines N-Triples, a concrete syntax for + RDF [RDF11-CONCEPTS]. + N-Triples is an easy to parse line-based subset of + Turtle [TURTLE]. +

+ +

The syntax is a revised version of N-Triples as originally defined in the RDF Test Cases [RDF-TESTCASES] document. Its original intent was for writing test cases, but it has proven to be popular as an exchange format for RDF data.

+

An N-Triples document contains no parsing directives. +

+

N-Triples triples are a sequence of RDF terms representing the subject, predicate and object of an RDF Triple. These may be separated by white space (spaces U+0020 or tabs U+0009). This sequence is terminated by a '.' and a new line (optional at the end of a document). +

+ +
Example 1
+ +

+ N-Triples triples are also Turtle simple triples, but Turtle includes other representations of RDF terms and abbreviations of RDF Triples. When parsed by a Turtle parser, data in the N-Triples format will produce exactly the same triples as a parser for the N-triples language. +

+

The RDF graph represented by an N-Triples document contains + exactly each triple matching the N-Triples + triple + production. +

+ +
+ + +

2. N-Triples Language

+
+

2.1 Simple Triples

+

The simplest triple statement is a sequence of (subject, predicate, object) terms, separated by whitespace and terminated by '.' after each triple.

+
Example 2
+
+
+

2.2 IRIs

+ +

+ IRIs may be written only as absolute IRIs. + IRIs are enclosed in '<' and '>' and may contain numeric escape sequences (described below). For example <http://example.org/#green-goblin>. +

+
+
+

2.3 RDF Literals

+ +

Literals + are used to identify values such as strings, numbers, + dates.

+ +

+ Literals (Grammar production Literal) have a lexical form followed by a language tag, a datatype IRI, or neither. + The representation of the lexical form consists of an + initial delimiter " (U+0022), a sequence of permitted + characters or numeric escape sequence or string escape sequence, and a final delimiter. Literals may not contain the characters ", LF, CR except in their escaped forms. In addition '\' (U+005C) may not appear in any quoted literal except as part of an escape sequence. + The corresponding RDF lexical form is the characters between the delimiters, after processing any escape sequences. + If present, the language tag is preceded by a '@' (U+0040). + If there is no language tag, there may be a datatype IRI, preceded by '^^' (U+005E U+005E). If there is no datatype IRI and no language tag it is a simple literal and the datatype is http://www.w3.org/2001/XMLSchema#string. +

+
Example 3
+
+
+

2.4 RDF Blank Nodes

+

+ RDF blank nodes in N-Triples are expressed as _: followed by a blank node label which is a series of name characters. + The characters in the label are built upon PN_CHARS_BASE, liberalized as follows: +

+
    +
  • The characters _ and [0-9] may appear anywhere in a blank node label.
    • +
  • The character . may appear anywhere except the first or last character.
    • +
  • The characters -, U+00B7, U+0300 to U+036F and U+203F to U+2040 are permitted anywhere except the first character.
    • +
+

+ A fresh RDF blank node is allocated for each unique blank node label in a document. + Repeated use of the same blank node label identifies the same RDF blank node. +

+
Example 4
+
+ +
+ +
+ + +

3. Changes from RDF Test Cases format

This section is non-normative.

+
    +
  • Encoding is UTF-8 rather than US-ASCII +
  • Uses IRIs rather than RDF URI References +
  • Defines a unique media type application/n-triples +
  • Subset of Turtle rather than Notation 3 +
  • Comments may occur after a triple production +
  • Allows \b and \f for backspace and form feed +
  • More than one way to represent a single character +
  • Blank node labels may start with a digit +
+
+ +
+ + +

4. A Canonical form of N-Triples

+

This section defined a canonical form of N-Triples which has + less variability in layout. The grammar for the language is the + same. Implementers are encouraged to produce this form.

+

Canonical N-Triples has the following additional constraints on layout:

+
    +
  • The whitespace following subject, + predicate, + and object MUST be a single space, + (U+0020). All other locations that allow + whitespace MUST be empty.
    • +
  • There MUST be no comments.
    • +
  • HEX MUST use only uppercase letters ([A-F]).
    • +
  • Characters MUST NOT be represented by UCHAR.
    • +
  • Within STRING_LITERAL_QUOTE, + only the characters + U+0022, U+005C, U+000A, U+000D + are encoded using ECHAR. + ECHAR MUST NOT be used for characters that are + allowed directly in + STRING_LITERAL_QUOTE.
    • +
+
+ +
+ +

5. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

+ The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, + and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. +

+ +

This specification defines conformance criteria for:

+
    +
  • N-Triples documents +
  • Canonical N-Triples documents +
  • N-Triples parsers +
+ +

A conforming N-Triples document is a Unicode string that conforms to the grammar and additional constraints defined in section 7. Grammar, starting with the ntriplesDoc production. An N-Triples document serializes an RDF graph.

+ +

A conforming Canonical N-Triples document is an + N-Triples document that follows the + additional constraints of Canonical N-Triples.

+ +

A conforming N-Triples parser is a system capable of reading N-Triples documents on behalf of an application. It makes the serialized RDF graph, as defined in section 8. Parsing, available to the application, usually through some form of API.

+ +

The IRI that identifies the N-Triples language is: +http://www.w3.org/ns/formats/N-Triples

+
+ +
+ + +

6. Media Type and Content Encoding

+ +

The media type of N-Triples is application/n-triples. + The content encoding of N-Triples is always UTF-8. + See N-Triples Media Type for the media type + registration form. +

+ +
+

6.1 Other Media Types

+

N-Triples has been historically provided with other media types. N-Triples may also be provided as text/plain. When used in this way N-Triples MUST use the escaped form of any character outside US-ASCII. As N-Triples is a subset of Turtle an N-Triples document MAY also be provided as text/turtle. In both of these cases the document is not an N-Triples document as an N-Triples document is only provided as application/n-triples.

+
+ +
+ +
+ + +

7. Grammar

+

An N-Triples document is a Unicode [UNICODE] character string encoded in UTF-8. + Unicode code points only in the range U+0 to U+10FFFF inclusive are allowed.

+

White space (tab U+0009 or space U+0020) is used to separate two terminals which would otherwise be (mis-)recognized as one terminal. White space is significant in the production STRING_LITERAL_QUOTE.

+

Comments in N-Triples take the form of '#', + outside an IRIREF or STRING_LITERAL_QUOTE, and continue + up-to, and excluding, the end of line (EOL), + or end of file if there is no end of line after the comment + marker. Comments are treated as white space.

+ +

The EBNF used + here is defined in XML 1.0 + [EBNF-NOTATION].

+ +

Escape sequence rules are the same as Turtle + [TURTLE]. However, as only the STRING_LITERAL_QUOTE production is allowed new lines in literals MUST be escaped.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1]ntriplesDoc::=triple? (EOL triple)* EOL?
[2]triple::=subject predicate object '.'
[3]subject::=IRIREF | BLANK_NODE_LABEL
[4]predicate::=IRIREF
[5]object::=IRIREF | BLANK_NODE_LABEL | literal
[6]literal::=STRING_LITERAL_QUOTE ('^^' IRIREF | LANGTAG)?

Productions for terminals

[144s]LANGTAG::='@' [a-zA-Z]+ ('-' [a-zA-Z0-9]+)*
[7]EOL::=[#xD#xA]+
[8]IRIREF::='<' ([^#x00-#x20<>"{}|^`\] | UCHAR)* '>'
[9]STRING_LITERAL_QUOTE::='"' ([^#x22#x5C#xA#xD] | ECHAR | UCHAR)* '"'
[141s]BLANK_NODE_LABEL::='_:' (PN_CHARS_U | [0-9]) ((PN_CHARS | '.')* PN_CHARS)?
[10]UCHAR::='\u' HEX HEX HEX HEX | '\U' HEX HEX HEX HEX HEX HEX HEX HEX
[153s]ECHAR::='\' [tbnrf"'\]
[157s]PN_CHARS_BASE::=[A-Z] | [a-z] | [#x00C0-#x00D6] | [#x00D8-#x00F6] | [#x00F8-#x02FF] | [#x0370-#x037D] | [#x037F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[158s]PN_CHARS_U::=PN_CHARS_BASE | '_' | ':'
[160s]PN_CHARS::=PN_CHARS_U | '-' | [0-9] | #x00B7 | [#x0300-#x036F] | [#x203F-#x2040]
[162s]HEX::=[0-9] | [A-F] | [a-f]
+
+
+ +
+ + +

8. Parsing

+

Parsing N-Triples requires a state of one item:

+
    +
  • Map[string -> blank node] bnodeLabels — A mapping from string to blank node.
    • +
+ +
+

8.1 RDF Term Constructors

+

This table maps productions and lexical tokens to RDF terms or components of RDF terms listed in section 8. Parsing:

+ + + + + + + + + + + +
productiontypeprocedure
IRIREF IRI The characters between "<" and ">" are taken, with escape sequences unescaped, to form the unicode string of the IRI.
STRING_LITERAL_QUOTE lexical formThe characters between the outermost '"'s are taken, with escape sequences unescaped, to form the unicode string of a lexical form.
LANGTAG language tagThe characters following the @ form the unicode string of the language tag.
literal literal The literal has a lexical form of the first rule argument, STRING_LITERAL_QUOTE, and either a language tag of LANGTAG or a datatype IRI of iri, depending on which rule matched the input. If the LANGTAG rule matched, the datatype is rdf:langString and the language tag is LANGTAG. If neither a language tag nor a datatype IRI is provided, the literal has a datatype of xsd:string.
BLANK_NODE_LABEL blank node The string after '_:', is a key in bnodeLabels. If there is no corresponding blank node in the map, one is allocated.
+
+
+

8.2 RDF Triple Construction

+

An N-Triples document defines an RDF graphs composed of a set of RDF triples. The triple production produces a triple defined by the terms constructed for subject, predicate and object. +

+ + +
+ +
+ + +

9. Acknowledgements

This section is non-normative.

+

The editor of the RDF 1.1 edition acknowledges valuable contributions from Gregg Kellogg, Eric Prud'hommeaux, Dave Beckett, David Robillard, Gregory Williams, Pat Hayes, Richard Cyganiak, Henry S. Thompson, +Peter Ansell, Evan Patton and David Booth.

+

This specification is a product of extended deliberations by the + members of the RDF Working Group. + It draws upon the earlier specification in RDF Test Cases, edited by Dave Beckett.

+
+ +
+ + +

A. Change log

+
+

A.1 Changes between Proposed Recommendation and Recommendation

+ +
+
+

A.2 Changes between Candidate Recommendation and Proposed Recommendation

+
    +
  • A normative reference to RDF Concepts was added.
    • +
  • The text for "Canonical N-Triples" has been made into a separate section.
    • +
+
+
+

A.3 Changes between Last Call Working Draft and Candidate recommendation

+

No substantive changes.

+
+
+

A.4 Changes between Last Call Working Draft and publication as Note

+
    +
  • Section defines canonical + N-Triples document. +
  • White space rules defined outside of grammar, as in Turtle. +
  • Comment processing defined. +
  • Parsing is defined. +
  • Removed "Summary of differences in N-Triples and Turtle". +
  • Recommendation track, not a working group Note. +
+
+
+ +
+ + +

B. N-Triples Internet Media Type, File Extension and Macintosh File Type

+
+
Contact:
+
Eric Prud'hommeaux
+
See also:
+ +
How to Register a Media Type for a W3C Specification
+
Internet Media Type registration, consistency of use
TAG Finding 3 June 2002 (Revised 4 September 2002)
+
+

The Internet Media Type / MIME Type for N-Triples is "application/n-triples".

+

It is recommended that N-Triples files have the extension ".nt" (all lowercase) on all platforms.

+ +

It is recommended that N-Triples files stored on Macintosh HFS file systems be given a file type of "TEXT".

+

This information that follows will be submitted to the IESG for review, approval, and registration with IANA.

+
+
Type name:
+
application
+ +
Subtype name:
+
n-triples
+
Required parameters:
+
None
+
Optional parameters:
+
None
+ +
Encoding considerations:
+
The syntax of N-Triples is expressed over code points in Unicode [UNICODE]. The encoding is always UTF-8 [UTF-8].
+
Unicode code points may also be expressed using an \uXXXX (U+0 to U+FFFF) or \UXXXXXXXX syntax (for U+10000 onwards) where X is a hexadecimal digit [0-9A-F]
+
Security considerations:
+
N-Triples is a general-purpose assertion language; applications may evaluate given data to infer more assertions or to dereference IRIs, invoking the security considerations of the scheme for that IRI. Note in particular, the privacy issues in [RFC3023] section 10 for HTTP IRIs. Data obtained from an inaccurate or malicious data source may lead to inaccurate or misleading conclusions, as well as the dereferencing of unintended IRIs. Care must be taken to align the trust in consulted resources with the sensitivity of the intended use of the data; inferences of potential medical treatments would likely require different trust than inferences for trip planning.
+ +
N-Triples is used to express arbitrary application data; security considerations will vary by domain of use. Security tools and protocols applicable to text (e.g. PGP encryption, MD5 sum validation, password-protected compression) may also be used on N-Triples documents. Security/privacy protocols must be imposed which reflect the sensitivity of the embedded information.
+
N-Triples can express data which is presented to the user, for example, RDF Schema labels. Application rendering strings retrieved from untrusted N-Triples documents must ensure that malignant strings may not be used to mislead the reader. The security considerations in the media type registration for XML ([RFC3023] section 10) provide additional guidance around the expression of arbitrary data and markup.
+
N-Triples uses IRIs as term identifiers. Applications interpreting data expressed in N-Triples should address the security issues of + Internationalized Resource Identifiers (IRIs) [RFC3987] Section 8, as well as + Uniform Resource Identifier (URI): Generic Syntax [RFC3986] Section 7.
+ +
Multiple IRIs may have the same appearance. Characters in different scripts may + look similar (a Cyrillic "о" may appear similar to a Latin "o"). A character followed + by combining characters may have the same visual representation as another character + (LATIN SMALL LETTER E followed by COMBINING ACUTE ACCENT has the same visual representation + as LATIN SMALL LETTER E WITH ACUTE). + + + + Any person or application that is writing or interpreting data in Turtle must take care to use the IRI that matches the intended semantics, and avoid IRIs that make look similar. + Further information about matching of similar characters can be found + in Unicode Security Considerations [UNICODE-SECURITY] and + Internationalized Resource Identifiers (IRIs) [RFC3987] Section 8. +
+ +
Interoperability considerations:
+
There are no known interoperability issues.
+
Published specification:
+
This specification.
+
Applications which use this media type:
+ +
No widely deployed applications are known to use this media type. It may be used by some web services and clients consuming their data.
+
Additional information:
+
Magic number(s):
+
None.
+
File extension(s):
+
".nt"
+ +
Macintosh file type code(s):
+
"TEXT"
+
Person & email address to contact for further information:
+ +
Eric Prud'hommeaux <eric@w3.org>
+
Intended usage:
+
COMMON
+
Restrictions on usage:
+
None
+
Author/Change controller:
+ +
The N-Triples specification is the product of the RDF WG. The W3C reserves change control over this specifications.
+
+
+ + +
+ +

C. References

C.1 Normative references

[EBNF-NOTATION]
Tim Bray; Jean Paoli; C. M. Sperberg-McQueen; Eve Maler; François Yergeau. EBNF Notation 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/REC-xml/#sec-notation +
[RDF-TESTCASES]
jan grant; Dave Beckett. RDF Test Cases. 10 February 2004. W3C Recommendation. URL: http://www.w3.org/TR/rdf-testcases +
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-concepts/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3023]
M. Murata; S. St.Laurent; D. Kohn. XML Media Types (RFC 3023). January 2001. RFC. URL: http://www.ietf.org/rfc/rfc3023.txt +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt +
[TURTLE]
Eric Prud'hommeaux, Gavin Carothers. RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-turtle-20140225/. The latest edition is available at http://www.w3.org/TR/turtle/ +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[UTF-8]
F. Yergeau. UTF-8, a transformation format of ISO 10646. IETF RFC 3629. November 2003. URL: http://www.ietf.org/rfc/rfc3629.txt +

C.2 Informative references

[UNICODE-SECURITY]
Mark Davis; Michel Suignard. Unicode Security Considerations. URL: http://www.unicode.org/reports/tr36/ +
\ No newline at end of file diff --git a/docs/standards/references/rdf-canon.html b/docs/standards/references/rdf-canon.html new file mode 100644 index 0000000..6ad423f --- /dev/null +++ b/docs/standards/references/rdf-canon.html @@ -0,0 +1,6218 @@ + + + + + + + + + +RDF Dataset Canonicalization + + + + + + + + + + + + + + + + + + +
+

+

RDF Dataset Canonicalization

A Standard RDF Dataset Canonicalization Algorithm

+

W3C Recommendation

+
+ More details about this document +
+
This version:
+ https://www.w3.org/TR/2024/REC-rdf-canon-20240521/ +
+
Latest published version:
+ https://www.w3.org/TR/rdf-canon/ +
+
Latest editor's draft:
https://w3c.github.io/rdf-canon/spec/
+
History:
+ https://www.w3.org/standards/history/rdf-canon/ +
+ Commit history +
+
Test suite:
https://w3c.github.io/rdf-canon/tests/
+
Implementation report:
+ https://w3c.github.io/rdf-canon/reports/ +
+ + + +
Editors:
+ Dave Longley (Digital Bazaar) +
+ Gregg Kellogg +
+ Dan Yamamoto +
+
+ Former editor: +
+ Manu Sporny (Digital Bazaar) (CG Report) +
+
Author:
+ Dave Longley (Digital Bazaar) +
+
Feedback:
+ GitHub w3c/rdf-canon + (pull requests, + new issue, + open issues) +
public-rch-wg@w3.org with subject line [rdf-canon] … message topic … (archives)
+
Errata:
Errata exists.
+ +
+
+

+ See also + + translations. +

+ +

+ Copyright + © + 2010-2024 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+

RDF [RDF11-CONCEPTS] describes a graph-based data model for making claims + about the world and provides the foundation for reasoning upon that graph + of information. At times, it becomes necessary to compare the differences + between sets of graphs, digitally sign them, or generate short identifiers + for graphs via hashing algorithms. This document outlines an algorithm for + normalizing RDF datasets such that these operations can be + performed.

+
+ +

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

This document describes the RDFC-1.0 algorithm for canonicalizing + RDF datasets, which was the input from the + W3C Credentials Community Group + published as [CCG-RDC-FINAL].

+ +

At the time of publication, [RDF11-CONCEPTS] is the most recent recommendation + defining RDF datasets and [N-QUADS], + however work on an updated specification + is ongoing within the W3C RDF-star Working Group. + Some dependencies from relevant updated specifications are provided + normatively in this specification with the expectation + that a future update to this specification will replace those with normative + references to updated RDF specifications.

+

+ This document was published by the RDF Dataset Canonicalization and Hash Working Group as + a Recommendation using the + Recommendation track. +

+ W3C recommends the wide deployment of this specification as a standard for + the Web. +

+ A W3C Recommendation is a specification that, after extensive + consensus-building, is endorsed by + W3C and its Members, and + has commitments from Working Group members to + royalty-free licensing + for implementations. + Future updates to this Recommendation may incorporate + new features. +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+ +

1. Introduction

This section is non-normative.

+ + +

When data scientists discuss canonicalization, + they do so in the context of achieving a particular set of goals. + Since the same information may sometimes be expressed in a variety of different ways, + it often becomes necessary to transform each of these + different ways into a single, standard representation. + With a standard representation, the differences between + two different sets of data can be easily determined, + a cryptographically-strong hash identifier can be generated for a particular + set of data, + and a particular set of data may be digitally-signed for later + verification.

+ +

In particular, this specification is about normalizing + RDF datasets, which are collections of graphs. Since + a directed graph can express the same information in more than one + way, it requires canonicalization to achieve the aforementioned goals + and any others that may arise via serendipity.

+ +

Most RDF datasets can be canonicalized fairly quickly, in terms + of algorithmic time complexity. However, those that contain nodes that do + not have globally unique identifiers pose a greater challenge. Normalizing + these datasets presents the graph isomorphism problem, a + problem that is believed to be difficult to solve quickly in the worst + case. Fortunately, existing real world data is rarely, if ever, modeled in + a way that manifests as the worst case and new data can be modeled to avoid + it. In fact, software systems that detect a problematic dataset + (see 7.1 Dataset Poisoning) can choose + to assume it's an attempted denial of service attack, rather than a + real input, and abort.

+ +

This document outlines an algorithm for generating a canonical + serialization of an RDF dataset given an RDF dataset as input. + The algorithm is called the + RDF Canonicalization algorithm version 1.0 or + RDFC-1.0.

+ +
Note
+

RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS] lacks clarity on the representation of + language-tagged strings, + where language tags of the form xx-YY + are treated as being case insensitive. Implementations might represent language tags + using all lower case in the form xx-yy, + retain the original representation xx-YY, + or use [BCP47] formatting conventions, + leading to different canonical forms, and therefore, different hashed values.

+
    +
  • The Canonicalization algorithm is based on the RDF 1.1 definition, + in the sense that the language tag xx-YY + is case insensitive, which might lead to different canonicalizations if the user is not aware of this problem.
    • +
  • User communities ought to agree to use lower case + language tags, + while being aware that some implementations might normalize language tags, + affecting hash values.
    • +
  • Future evolution of RDF might regulate this issue, which RDF environments might have to adapt to, + and this might lead to an update of RDFC-1.0.
    • +
+ +
+
Note

See B. URDNA2015 + for a comparison with the version of the algorithm published + in RDF Dataset Canonicalization [CCG-RDC-FINAL].

+ +

1.1 Uses of Dataset Canonicalization

+ +

There are different use cases where graph or dataset canonicalization are important:

+
    +
  • Determining if one serialization is isomorphic to another.
    • +
  • Digital signing of graphs (datasets) independent of serialization or format.
    • +
  • Comparing two graphs (datasets) to find differences.
    • +
  • Communicating change sets when remotely updating an RDF source.
    • +
+

A canonicalization algorithm is necessary, but not necessarily sufficient, to handle many of these use cases. The use of blank nodes in RDF graphs and datasets has a long history and creates inevitable complexities. Blank nodes are used for different purposes:

+
    +
  • when a well known identifier for a node is not known, or the author of a document chooses not to unambiguously name that node,
    • +
  • when a node is used to stitch together parts of a graph and the nodes themselves are not interesting (e.g., RDF Collections in [RDF11-MT]),
    • +
  • when someone is trying to create an intentionally difficult graph topology.
    • +
+

Furthermore, + RDF semantics dictate that deserializing an RDF document + results in the creation of unique blank nodes, + unless it can be determined that on each occasion, + the blank node identifies the same resource. + This is due to the fact that blank node identifiers + are an aspect of a concrete RDF syntax + and are not intended to be persistent or portable. + Within the abstract RDF model, + blank nodes do not have identifiers + (although some + RDF store + implementations may use stable identifiers and may choose to make them portable). + See Blank Nodes + in [RDF11-CONCEPTS] for more information.

+ +

RDF does have a provision for allowing blank nodes + to be published in an externally identifiable way through the use of + Skolem IRIs, + which allow a given RDF store to replace the use of blank nodes + in a concrete syntax with IRIs, + which then serve to repeatably identify that blank node within that particular RDF store; + however, this is not generally useful for talking about the + same graph in different RDF stores, + or other concrete representations. + In any case, a stable blank node identifier defined for one + RDF store or serialization is arbitrary, + and typically not relatable to the context within which it is used.

+ +

This specification defines an algorithm for creating stable + blank node identifiers repeatably for different serializations + possibly using individualized blank node identifiers + of the same RDF graph (dataset) by grounding each blank node + through the nodes to which it is connected. + As a result, a graph signature can be obtained by hashing a canonical serialization + of the resulting canonicalized dataset, + allowing for the isomorphism and digital signing use cases. + This specification does not define such a graph signature.

+ +

As blank node identifiers can be stable even with other changes to a graph (dataset), + in some cases it is possible to compute the difference between two graphs (datasets), + for example if changes are made only to ground triples, + or if new blank nodes are introduced which do not create an automorphic confusion + with other existing blank nodes. + If any information which would change the generated blank node identifier, + a resulting diff might indicate a greater set of changes than actually exists. + Additionally, if the starting dataset is an N-Quads document, + it may be possible to correlate the original blank node identifiers + used within that N-Quads document with those issued in the + canonicalized dataset.

+ +
Note

Although alternative hash algorithms might be used + with this specification, + applications ought to carefully weigh the advantages + and disadvantages of using an alternative hash function. + This is the case, in particular, for any representation of the canonical n-quads form + or issued identifiers map + that does not identify the associated hash algorithm. Any use case + that requires reproduction of the same output is expected to + unequivocally express or communicate the internal + hash algorithm that was used when generating + the canonical n-quads form. +

+
+ +

1.2 How to Read this Document

+ + +

This document is a detailed specification for an RDF dataset + canonicalization algorithm. The document is primarily intended for the + following audiences:

+ +
    +
  • Software developers that want to implement an RDF dataset + canonicalization algorithm.
    • +
  • Masochists.
    • +
+ +

To understand the basics in this specification you must be familiar with + basic RDF concepts [RDF11-CONCEPTS]. A working knowledge of + graph theory and + graph isomorphism + is also recommended.

+
+ +

1.3 Typographical conventions

This section is non-normative.

+ +

The following typographic conventions are used in this specification:

+ +
+
markup
+ Markup (elements, attributes, properties), + machine processable values (string, characters, media types), + property names, + and file names are in red-orange monospace font.
+
variable
+ A variable in pseudo-code or in an algorithm description is italicized.
+
definition
+ A definition of a term, to be used elsewhere in this or other specifications, + is italicized and in bold.
+
definition reference
+ A reference to a definition in this document + is underlined and is also an active link to the definition itself.
+
markup definition reference
+ References to a definition in this document, + when the reference itself is also a markup, is underlined, + in a red-orange monospace font, and is also an active link to the definition itself.
+
external definition reference
+ A reference to a definition in another document + is underlined and italicized, and is also an active link to the definition itself.
+
markup external definition reference
+ A reference to a definition in another document, + when the reference itself is also a markup, + is underlined and italicized in a red-orange monospace font, + and is also an active link to the definition itself.
+
hyperlink
+ A hyperlink is underlined and in blue.
+
[reference]
+ A document reference (normative or informative) is enclosed in square brackets + and links to the references section.
+
Explanation
+ An expandable area to find a more detailed, non-normative explanation of a + particular algorithmic step. +
+ Explanation +

This area would provide more information about the step involved.

+
+
+
Logging
+ An expandable area to find suggestions for implementations to log + information about processing, + which may be useful in comparing with other implementations, + or with logs provided with each test case. +
+ Logging +

For example, the following output snippet might + describe the operation of an implementation using the [YAML] format.

+ 
ca:
+  ca2:
+    bn_to_quads:
+      e0:
+        - _:e0 <http://example.com/#p1> _:e1 .
+      e1:
+        ...
+  ca3:
+  - identifier: e0
+    h1dq:
+      nquads:
+        - _:a <http://example.com/#p1> _:z .
+
+
+
+ +
Note

Notes are in light green boxes with a green left border and with a "Note" header in green. + Notes are always informative.

+ +
+
+ Example 1 + 
Examples are in light khaki boxes, with khaki left border,
+and with a numbered "Example" header in khaki.
+Examples are always informative. The content of the example is in monospace font and may be 
+syntax colored.
+
+Examples may have tabbed navigation buttons
+to show the results of transforming an example into other representations.
+
+Code examples are generally given in a Turtle or TriG format for brevity,
+where each line represents a single triple or quad.
+Additionally, have the following implied directives:
+
+BASE <http://example.com/>
+PREFIX : <#>
+
+Following the Turtle/TriG syntax rules, blank nodes always appear in the 
+`_:xyz` format.
+
+
+
+
+ +

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ The key words MUST, MUST NOT, and SHOULD in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+

A conforming processor is a system which can generate + the canonical n-quads form of an input dataset + consistent with the algorithms defined in this specification.

+ +

The algorithms in this specification are normative, + because to consistently reproduce the same canonical identifiers, + implementations MUST strictly conform to the steps outlined in these algorithms.

+ +
Note

Implementers can partially check their level of conformance with + this specification by successfully passing the test cases of the + RDF Dataset Canonicalization test suite. + Note, however, that passing all the tests in the test + suite does not imply complete conformance to this specification. It only implies + that the implementation conforms to the aspects tested by the test suite.

+
+ +

3. Terminology

+ + +

3.1 Terms defined by this specification

+ +
canonical n-quads form
+
+ The canonicalized representation of a quad is defined in A. A Canonical form of N-Quads. + A quad in canonical n-quads form represents a graph name, if present, in the same manner as + a subject, and each quad is terminated with a single LF (line feed, code point U+000A). +
+
canonicalization function
+
A canonicalization function maps RDF datasets + into isomorphic datasets [RDF11-CONCEPTS]. + Two datasets produce the same canonical result if and only if they are isomorphic. + The RDFC-1.0 algorithm implements a canonicalization function. + Some datasets may be constructed to prevent this algorithm from + terminating in a reasonable amount of time (see 7.1 Dataset Poisoning), + in which case the algorithm can be considered to be + a partial canonicalization function. + +
canonicalized dataset
+
A canonicalized dataset is the combination of the following: + + A concrete serialization of a canonicalized dataset MUST label + all blank nodes using the canonical blank node identifiers. +
+
gossip path
+
A particular enumeration of every incident mention emanating + from a blank node. This recursively includes transitively related + mentions until any named node or blank node already labeled by + a particular identifier issuer is reached. Gossip paths are + encoded and operated on in the RDFC-1.0 algorithm as strings. (See + 4.8 Hash N-Degree Quads for more information + on the construction of gossip paths.) +
+
hash
+
The lowercase, hexadecimal representation of a message digest.
+
hash algorithm
+
The default hash algorithm used by RDFC-1.0, namely, SHA-256 [FIPS-180-4]. +

Implementations MUST support a parameter to define the hash algorithm, + MUST support SHA-256 and SHA-384 [FIPS-180-4], + and SHOULD support the ability to specify other hash algorithms. + Using a different hash algorithm will generally result in different output than + using the default.

+ +
Note

There is no expectation that the default hash algorithm + will also be used by any application creating a hash digest of the + canonical N-Quads result.

+
+
identifier issuer
+
An identifier issuer is used to issue new blank node identifiers. It + maintains a + blank node identifier issuer state.
+
input blank node identifier map
+
Records any blank node identifiers already assigned to the + input dataset. + If the input dataset is provided as an N-Quads document, + the map relates blank nodes in the abstract input dataset + to the blank node identifiers used within the N-Quads document, + otherwise, identifiers are assigned arbitrarily for + each blank node in the input dataset not previously identified. +
Note
Implementations or environments might deal with blank + node identifiers more directly; for example, some implementations might + retain blank node identifiers in the parsed or abstract dataset. Implementations + are expected to reuse these to enable usable mappings between input blank node + identifiers and output blank node identifiers outside of the algorithm.
+
+
input dataset
+
The abstract RDF dataset that is provided as input to + the algorithm.
+
mention
+
+ A node is mentioned in a quad + if it is a component of that quad, + as a subject, predicate, object, or graph name.
+
mention set
+
The set of all quads in a dataset + that mention a node n is called the mention set of n, + denoted Qn.
+
quad
+
A tuple composed of subject, predicate, object, and graph name. + This is a generalization of an RDF triple along with a graph name. +
+
+
+ +

3.2 Terms defined by cited specifications

+ +
blank node
+
A blank node + as specified by [RDF11-CONCEPTS]. In short, it is a node in a graph that is + neither an IRI, nor a + literal.
+
blank node identifier
+
A blank node identifier + as specified by [RDF11-CONCEPTS]. In short, it is a string that begins + with _: that is used as an identifier for a + blank node. Blank node identifiers + are typically implementation-specific local identifiers; this document + specifies an algorithm for deterministically specifying them.
+
+ Concrete syntaxes, like [Turtle] or [N-Quads], prepend blank node identifiers with the _: string + to differentiate them from other nodes in the graph. This affects the + canonicalization algorithm, which is based on calculating a hash over the representations of quads in this format. +
+
default graph
+
The default graph + as specified by [RDF11-CONCEPTS].
+
graph name
+
A graph name + as specified by [RDF11-CONCEPTS].
+
IRI
+
An IRI (Internationalized Resource Identifier) is a string that conforms to the syntax + defined in [RFC3987].
+
object
+
An object + as specified by [RDF11-CONCEPTS].
+
predicate
+
A predicate + as specified by [RDF11-CONCEPTS].
+
RDF dataset
+
A dataset + as specified by [RDF11-CONCEPTS]. + For the purposes of this specification, an RDF dataset + is considered to be a set of quads
+
RDF graph
+
An RDF graph + as specified by [RDF11-CONCEPTS].
+
RDF triple
+
A triple + as specified by [RDF11-CONCEPTS].
+
string
+ A string is a sequence of zero or more Unicode characters.
+
subject
+
A subject + as specified by [RDF11-CONCEPTS].
+
true and false
+ Values that are used to express one of two possible boolean states.
+
Unicode code point order
+
This refers to determining the order of two Unicode strings (A and B), + using Unicode Codepoint Collation, + as defined in [XPATH-FUNCTIONS], + which defines a + total ordering + of strings comparing code points. + Note that for UTF-8 encoded strings, comparing the byte sequences gives the same result as code point order. +
+
+
+ +

4. Canonicalization

+ + +

Canonicalization is the process of transforming an + input dataset to its serialized canonical form. + That is, any two input datasets that contain the same information, + regardless of their arrangement, + will be transformed into the same serialized canonical form. + The problem requires directed + graphs to be deterministically ordered into sets of nodes and edges. This + is easy to do when all of the nodes have globally-unique identifiers, but + can be difficult to do when some of the nodes do not. Any nodes without + globally-unique identifiers must be issued deterministic identifiers.

+ +
Note

+ This specification defines a canonicalized dataset to include stable identifiers for blank nodes, + practical uses of which will always generate a canonical serialization of such a dataset.

+ +

In time, there may be more than one canonicalization algorithm and, + therefore, for identification purposes, this algorithm is named the + "RDF Canonicalization algorithm version 1.0" + (RDFC-1.0).

+ +

Figure 1 provides an overview of RDFC-1.0, + with steps 1 through 7 corresponding to the various steps described in + 4.4.3 Algorithm.

+ +
+ + +

+ The image represents an overview of the RDFC-1.0 algorithm. + The Input Document is deserialized into the Input Dataset + and Input Blank Node Identifier Map. + Canonicalization steps 1-6 are executed resulting in + the Canonicalized Dataset including the + Input Blank Node Identifier Map and Issued Identifiers Map. + Step 7 of the Canonicalization algorithm creates + the canonical n-quads form of the Canonicalized Dataset.

+ +
Figure 1 An illustrated overview of the RDFC-1.0 algorithm.
+ Image available in + + SVG + .
+
+ +

4.1 Overview

This section is non-normative.

+ + +

To determine a canonical labeling, RDFC-1.0 considers the + information connected to each blank node. + Nodes with unique first degree information can immediately be issued a canonical identifier + via the Issue Identifier algorithm. + When a node has non-unique first degree information, + it is necessary to determine all information that is transitively connected + to it throughout the entire dataset. + 4.6 Hash First Degree Quads defines a + node’s first degree information via its first degree hash.

+ +

Hashes are computed from the information of each blank node. + These hashes encode the mentions incident to each blank node. + The hash of a string s, is the lower-case, + hexadecimal representation of the result of passing s + through a cryptographic hash function. + By default, RDFC-1.0 uses the SHA-256 hash algorithm [FIPS-180-4].

+ +
Note

The "degree" terminology is used within this specification + as colloquial way of describing + the eccentricity or + radius + of any two nodes within a dataset. + This concept is also related to "degrees of separation", + as in, for example, "six degrees of separation". + Nodes with unique first degree information can be considered nodes with a radius of one.

+
+ +

4.2 Canonicalization State

+ + +

When performing the steps required by the canonicalization algorithm, + it is helpful to track state in a data structure called the + canonicalization state. The information contained in the + canonicalization state is described below.

+ +
+
blank node to quads map
+
A map that relates a blank node identifier to + the quads in which they appear in the + input dataset.
+
hash to blank nodes map
+
A map that relates a hash to a + list of + blank node identifiers.
+
canonical issuer
+
An identifier issuer, initialized with the + prefix c14n (short for canonicalization), for issuing canonical + blank node identifiers. +
Note
+ Mapping all blank nodes to use this + identifier spec means that an RDF dataset composed of two + different RDF graphs will issue different + identifiers than that for the graphs taken independently. This may + happen anyway, due to automorphisms, + or overlapping statements, but an identifier based on the resulting + hash along with an issue sequence number specific to that hash would + stand a better chance of surviving such minor changes, and allow the + resulting information to be useful for RDF Diff. +
+
+
+
+ +

4.3 Blank Node Identifier Issuer State

+ + +

The canonicalization algorithm issues identifiers to blank nodes. + The Issue Identifier algorithm uses an + identifier issuer to accomplish this task. + The information an identifier issuer needs to keep track of is described + below.

+ +
+
identifier prefix
+
The identifier prefix is a string that is used at the beginning of an + blank node identifier. It should be initialized to a + string that is specified by the canonicalization algorithm. When + generating a new blank node identifier, the prefix + is concatenated with a identifier counter. For example, + c14n is a proper initial value for the + identifier prefix that would produce + blank node identifiers like c14n1.
+
identifier counter
+
A counter that is appended to the identifier prefix to + create an blank node identifier. It is initialized to + 0.
+
issued identifiers map
+
An ordered map that relates blank node identifiers to issued identifiers, + to prevent issuance of more than one new identifier per existing identifier, + and to allow blank nodes to + be assigned identifiers some time after issuance.
+
+
+ +

4.4 Canonicalization Algorithm

+ + +

The canonicalization algorithm converts an input dataset + into a canonicalized dataset or raises an error if + the input dataset is determined to be overly complex. + This algorithm will assign + deterministic identifiers to any blank nodes in the + input dataset.

+ +

4.4.1 Overview

This section is non-normative.

+ + +

RDFC-1.0 canonically labels an RDF dataset + by assigning each blank node a canonical identifier. + In RDFC-1.0, an RDF dataset D + is represented as a set of quads of the form < s, p, o, g > + where the graph component g is empty if and only if the + triple < s, p, o > is in the default graph. + It is expected that, for two RDF datasets, + RDFC-1.0 returns the same canonically labeled list of quads + if and only if the two datasets are isomorphic (i.e., the same modulo blank node identifiers). +

+ +

RDFC-1.0 consists of several sub-algorithms. + These sub-algorithms are introduced in the following sub-sections. + First, we give a high level summary of RDFC-1.0.

+ +
    +
  1. Initialization. + Initialize the state needed for the rest of the algorithm + using 4.2 Canonicalization State. + Also initialize the canonicalized dataset using the input dataset + (which remains immutable) + the input blank node identifier map + (retaining blank node identifiers from the input if possible, otherwise assigning them arbitrarily); + the issued identifiers map from the canonical issuer is added upon completion of the algorithm.
    2. +
  2. Compute first degree hashes. + Compute the first degree hash for each blank node in the dataset using 4.6 Hash First Degree Quads.
    3. +
  3. Canonically label unique nodes. + Assign canonical identifiers via 4.5 Issue Identifier Algorithm, + in Unicode code point order, to each blank node whose first degree hash is unique.
    4. +
  4. Compute N-degree hashes for non-unique nodes. + For each repeated first degree hash (proceeding in Unicode code point order), + compute the N-degree hash via 4.8 Hash N-Degree Quads + of every unlabeled blank node that corresponds to the given repeated hash.
    5. +
  5. Canonically label remaining nodes. + In Unicode code point order of the N-degree hashes, + issue canonical identifiers to each corresponding blank node using + 4.5 Issue Identifier Algorithm. + If more than one node produces the same N-degree hash, + the order in which these nodes receive a canonical identifier does not matter.
    6. +
  6. Finish. + Return the serialized canonical form of the canonicalized dataset. + Alternatively, return the canonicalized dataset containing + the input blank node identifier map and issued identifiers map.
    7. +
+
+ +

4.4.2 Examples

This section is non-normative.

+ + + + + +
+ +

4.4.3 Algorithm

+ + +

The following algorithm will run with a minimal number of iterations in each step + for typical input datasets. + In some extreme cases, the algorithm can behave poorly, particularly in Step 5. + Implementations MUST defend against potential denial-of-service attacks + by raising suitable exceptions and terminating early. + See 7.1 Dataset Poisoning for further information.

+ +
Note

Implementations can consider placing limits on the number of + calls to 4.8 Hash N-Degree Quads based on the number + of blank nodes in the hash to blank nodes map. + For most typical datasets, more than a couple + of iterations on 4.8 Hash N-Degree Quads per blank node would be unusual.

+ +
    +
  1. Create the canonicalization state. + If the input dataset is an N-Quads document, + parse that document into a dataset in the canonicalized dataset, + retaining any blank node identifiers used within that document + in the input blank node identifier map; + otherwise arbitrary identifiers are assigned for each + blank node. +
    + Explanation +

    This has the effect of initializing the + blank node to quads map, + and the hash to blank nodes map, + as well as instantiating a new canonical issuer.

    +

    After this algorithm completes, + the input blank node identifier map state + and canonical issuer may be used to + correlate blank nodes used in the + input dataset with both their original identifiers, + and associated canonical identifiers.

    +
    +
    2. +
  2. For every quad Q in input dataset: +
      +
    1. For each blank node that is a component of Q, + add a reference to Q from the + map entry for the + blank node identifier identifier + in the blank node to quads map, + creating a new entry if necessary, + using the identifier for the blank node found in the + input blank node identifier map. +
      + Explanation +

      This establishes the blank node to quads map, + relating each blank node with the set of quads + of which it is a component, + via the map for each blank node in the input dataset to its assigned identifier.

      +
      Note

      + Literal components of + quads are not subject to any normalization. + As noted in + Section 3.3 + of [RDF11-CONCEPTS], + literal term equality + is based on the + lexical form, + rather than the literal value, + so two literals "01"^^xsd:integer and "1"^^xsd:integer are treated as distinct resources. +

      +
      +
      2. +
    +
    + Logging +

    Log the state of the blank node to quads map:

    + 
    # Blank node to quads map for unique hashes example
+ca:
+  log point: Entering the canonicalization function (4.4.3).
+  ca.2:
+    log point: Extract quads for each bnode (4.4.3 (2)).
+    Bnode to quads:
+      e0:
+        - <http://example.com/#p> <http://example.com/#q> _:e0 .
+        - _:e0 <http://example.com/#s> <http://example.com/#u> .
+      e1:
+        - <http://example.com/#p> <http://example.com/#r> _:e1 .
+        - _:e1 <http://example.com/#t> <http://example.com/#u> .
+  ...
    +
    +
    3. +
  3. For each key n + in the blank node to quads map: +
    + Explanation +

    This step creates a hash for every blank node in the input document. + Some blank nodes will lead to a unique hash, + while other blank nodes may share a common hash.

    +
    +
      +
    1. Create a hash, hf(n), + for n according to the + Hash First Degree Quads algorithm.
      2. +
    2. Append n to the value associated to hf(n) in + hash to blank nodes map, + creating a new entry if necessary.
      3. +
    +
    + Logging +

    Log the results from the Hash First Degree Quads algorithm.

    + 
    # First degree hashes for unique hashes example
+ca:
+  ...
+  ca.3:
+    log point: Calculated first degree hashes (4.4.3 (3)).
+    with:
+      - identifier: e0
+        h1dq:
+          log point: Hash First Degree Quads function (4.6.3).
+          nquads:
+            - <http://example.com/#p> <http://example.com/#q> _:a .
+            - _:a <http://example.com/#s> <http://example.com/#u> .
+          hash: 21d1dd5ba21f3dee9d76c0c00c260fa6f5d5d65315099e553026f4828d0dc77a
+      - identifier: e1
+        h1dq:
+          log point: Hash First Degree Quads function (4.6.3).
+          nquads:
+            - <http://example.com/#p> <http://example.com/#r> _:a .
+            - _:a <http://example.com/#t> <http://example.com/#u> .
+          hash: 6fa0b9bdb376852b5743ff39ca4cbf7ea14d34966b2828478fbf222e7c764473
+  ...
    +
    +
    4. +
  4. For each hash to identifier list + map entry in + hash to blank nodes map, code point ordered by hash: +
    + Explanation +

    This step establishes the canonical identifier for blank nodes having + a unique hash, which are recorded in the canonical issuer.

    +
    +
      +
    1. If identifier list has more than one entry, + continue to the next mapping.
      2. +
    2. Use the + Issue Identifier algorithm, + passing canonical issuer and the + single blank node identifier, identifier in + identifier list to issue a + canonical replacement identifier for identifier.
      3. +
    3. Remove the map entry for hash from the + hash to blank nodes map.
      4. +
    +
    + Logging +

    Log the assigned canonical identifiers.

    + 
    # Assigned canonical identifiers for shared hashes example
+ca:
+  ...
+  ca.4:
+    log point: Create canonical replacements for hashes mapping to a single node (4.4.3 (4)).
+    with:
+      - identifier: e2
+        hash: 15973d39de079913dac841ac4fa8c4781c0febfba5e83e5c6e250869587f8659
+        canonical label: c14n0
+      - identifier: e3
+        hash: 7e790a99273eed1dc57e43205d37ce232252c85b26ca4a6ff74ff3b5aea7bccd
+        canonical label: c14n1
+  ...
    +
    +
    5. +
  5. For each hash to identifier list + map entry in + hash to blank nodes map, code point ordered by + hash: +
    + Explanation +

    This step establishes the canonical identifier for blank nodes having + a shared hash. + This is done by creating unique blank node identifiers for all + blank nodes traversed by the Hash N-Degree Quads algorithm, + running through each blank node without a canonical identifier in the order + of the hashes established in the previous step.

    +
    +
    + Logging +

    Log hash and identifier list for this iteration.

    + 
    # Hash and Identifier List for each iteration of step 5 using shared hashes example
+ca:
+  ...
+  ca.5:
+    log point: Calculate hashes for identifiers with shared hashes (4.4.3 (5)).
+    with:
+      - hash: 3b26142829b8887d011d779079a243bd61ab53c3990d550320a17b59ade6ba36
+        identifier list: [ "e0", "e1"]
+    ...
+  ...
    +
    +
      +
    1. Create hash path list where each item will be a result + of running the + Hash N-Degree Quads algorithm. +
      + Explanation +

      This list will be populated in step 5.2, and will establish an order for those blank nodes + sharing a common first-degree hash.

      +
      +
      2. +
    2. For each blank node identifier + n in identifier list: +
        +
      1. If a canonical identifier has already been issued for + n, continue to the next + blank node identifier.
        2. +
      2. Create temporary issuer, an + identifier issuer initialized with the prefix + b.
        3. +
      3. Use the + Issue Identifier algorithm, + passing temporary issuer and n, to + issue a new temporary blank node identifier bn + to n.
        4. +
      4. Run the + Hash N-Degree Quads algorithm, + passing the canonicalization state, + n for identifier, and + temporary issuer, + appending the + result to the hash path list. +
        + Logging +

        Include logs for each call to Hash N-Degree Quads algorithm.

        + 
        # Logs from calls to Hash N-Degree Quads algorithm for shared hashes example
+ca:
+  ...
+  ca.5:
+    log point: Calculate hashes for identifiers with shared hashes (4.4.3 (5)).
+    with:
+      - hash: 3b26142829b8887d011d779079a243bd61ab53c3990d550320a17b59ade6ba36
+        identifier list: [ "e0", "e1"]
+        ca.5.2:
+          log point: Calculate hashes for identifiers with shared hashes (4.4.3 (5.2)).
+          with:
+            - identifier: e0
+              hndq:
+                log point: Hash N-Degree Quads function (4.8.3).
+                identifier: e0
+                issuer: {e0: b0}
+                ...
+            ...
+        ...
+  ...
        +
        +
        5. +
      +
      3. +
    3. For each result in the hash path list, + code point ordered by the hash in result: +
      + Explanation +

      The previous step created temporary identifiers for the + blank nodes sharing a common first degree hash, + which is now used to generate their canonical identifiers.

      +
      +
        +
      1. For each blank node identifier, + existing identifier, that was issued a temporary + identifier by identifier issuer in result, + issue a canonical identifier, + in the same order, + using the Issue Identifier algorithm, + passing canonical issuer and existing identifier. +
        + Explanation +

        In Step 5.2, + hash path list was created with an ordered + set of results. + Each result contained a temporary issuer + which recorded temporary identifiers associated with + a particular blank node identifier in + identifier list. + This step processes each returned temporary issuer, + in order, and allocates canonical identifiers + to the temporary identifier mappings contained + within each temporary issuer, + creating a full order on the remaining blank nodes + with unissued canonical identifiers. +

        +
        +
        2. +
      +
      + Logging +

      Log newly issued canonical identifiers.

      + 
      # Newly issued canonical identifiers from step 5.3 for shared hashes example
+ca:
+  ...
+  ca.5:
+    log point: Calculate hashes for identifiers with shared hashes (4.4.3 (5)).
+    with:
+      - hash: 3b26142829b8887d011d779079a243bd61ab53c3990d550320a17b59ade6ba36
+        identifier list: [ "e0", "e1"]
+        ...
+        ca.5.3:
+          log point: Canonical identifiers for temporary identifiers (4.4.3 (5.3)).
+          issuer:
+              - blank node: e1
+                canonical identifier: c14n2
+              - blank node: e0
+                canonical identifier: c14n3
+  ...
      +
      +
      4. +
    +
    6. +
  6. Add the issued identifiers map + from the canonical issuer to the + canonicalized dataset. +
    + Explanation +

    This step adds the issued identifiers map + from the canonical issuer to the + canonicalized dataset, the keys in the + issued identifiers map are map entries in the + input blank node identifier map.

    +
    +
    + Logging +

    Log the state of the canonical issuer at the completion of the algorithm.

    + 
    # Canonical issuer state after step 6 for shared hashes example
+ca:
+  ...
+  ca.6:
+    log point: Issued identifiers map (4.4.3 (6)).
+    issued identifiers map: {e2: c14n0, e3: c14n1, e1: c14n2, e0: c14n3}
    +
    +
    7. +
  7. Return the serialized canonical form + of the canonicalized dataset. + Upon request, alternatively (or additionally) return the + canonicalized dataset itself, which includes the + input blank node identifier map, and + issued identifiers map from the canonical issuer. +
    Note

    Technically speaking, one implementation + might return a canonicalized dataset that maps + particular blank nodes to different identifiers than another + implementation, however, this only occurs when there are + isomorphisms in the dataset such that a canonically serialized + expression of the dataset would appear the same from either + implementation.

    +
    + Explanation +

    The serialized canonical form is an N-Quads + document where the blank node identifiers are taken + from the canonical identifiers associated with each blank node.

    +

    The canonicalized dataset is composed of the original + input dataset, the input blank node identifier map, + containing identifiers for each blank node in the input dataset, + and the canonical issuer, + containing an issued identifiers map + mapping the identifiers in the input blank node identifier map + to their canonical identifiers. +

    +
    +
    8. +
+
+
+ +

4.5 Issue Identifier Algorithm

+ + +

This algorithm issues a new blank node identifier for + a given existing blank node identifier. It also updates + state information that tracks the order in which new + blank node identifiers were issued. The order of issuance is + important for canonically labeling blank nodes that are isomorphic + to others in the dataset.

+ +

4.5.1 Overview

+ + +

The algorithm maintains an issued identifiers map to + relate an existing blank node identifier from the input dataset + to a new blank node identifier using a given identifier prefix + (c14n) with new identifiers issued by appending an incrementing number. + For example, when called for a blank node identifier such as e3, + it might result in a issued identifier of c14n1.

+
+ +

4.5.2 Algorithm

+ + +

The algorithm takes an identifier issuer I and an + existing identifier as inputs. The output is a new + issued identifier. The steps of the algorithm are:

+ +
    +
  1. If there is a + map entry for existing identifier in + issued identifiers map of I, + return it.
    2. +
  2. Generate issued identifier by concatenating + identifier prefix with the string value of + identifier counter.
    3. +
  3. Add an entry + mapping existing identifier to issued identifier + to the issued identifiers map of I.
    4. +
  4. Increment identifier counter.
    5. +
  5. Return issued identifier.
    6. +
+
+
+ +

4.6 Hash First Degree Quads

+ + +

This algorithm calculates a hash for a given blank node + across the quads in a dataset in which that blank node + is a component. + If the hash uniquely identifies that blank node, + no further examination is necessary. + Otherwise, a hash will be created for the blank node using + the algorithm in 4.8 Hash N-Degree Quads + invoked via 4.4 Canonicalization Algorithm.

+ +

4.6.1 Overview

This section is non-normative.

+ + +

To determine whether the first degree information of a node n is unique, + a hash is assigned to its mention set, + Qn. + The first degree hash of a blank node n, + denoted hf(n), + is the hash that results from 4.6 Hash First Degree Quads + when passing n. + Nodes with unique first degree hashes have unique first degree information.

+ +

For consistency, blank node identifiers used in Qn + are replaced with placeholders in a canonical n-quads serialization of that quad. + Every blank node component is replaced with either a or z, + depending on if that component is n or not.

+ +

The resulting serialized quads are then code point ordered, + concatenated, and hashed. + This hash is the first degree hash of n, hf(n).

+
+ +

4.6.2 Examples

This section is non-normative.

+ + + + + +
+ +

4.6.3 Algorithm

+ + +

This algorithm takes the canonicalization state and a + reference blank node identifier as inputs.

+ +
    +
  1. Initialize nquads to an empty list. + It will be used to store quads in canonical n-quads form.
    2. +
  2. Get the list of quads quads + from the map entry for + reference blank node identifier in the + blank node to quads map.
    3. +
  3. For each quad quad in quads: +
      +
    1. Serialize the quad in canonical n-quads form with the + following special rule: +
        +
      1. If any component in quad is an + blank node, then serialize it using a + special identifier as follows: +
          +
        1. If the blank node's existing + blank node identifier matches the + reference blank node identifier then use the + blank node identifier a, + otherwise, use the blank node identifier + z.
          2. +
        +
        2. +
      +
      2. +
    +
    4. +
  4. Sort nquads in Unicode code point order.
    5. +
  5. Return the hash that results from passing the sorted + and concatenated nquads through the + hash algorithm. +
    + Logging +

    Log the inputs and result of running this algorithm.

    + 
    # Inputs and hash result for the Hash First Degree Hash algorithm for unique hashes example
+h1dq:
+  log point: Hash First Degree Quads function (4.6.3).
+  nquads:
+    - <http://example.com/#p> <http://example.com/#q> _:a .
+    - _:a <http://example.com/#s> <http://example.com/#u> .
+  hash: 21d1dd5ba21f3dee9d76c0c00c260fa6f5d5d65315099e553026f4828d0dc77a
    +
    +
    6. +
+
+
+ + + +

4.8 Hash N-Degree Quads

+ + +

This algorithm calculates a hash for a given blank node + across the quads in a dataset in which that blank node + is a component for which the hash does not uniquely identify that blank node. + This is done by expanding the search from quads directly referencing that + blank node (the mention set), to those quads + which contain nodes which are also components of quads in the mention set, + called the gossip path. + This process proceeds in every greater degrees of indirection until + a unique hash is obtained.

+ +

4.8.1 Overview

This section is non-normative.

+ + +

Usually, when trying to determine if two nodes in a graph are + equivalent, you simply compare their identifiers. However, what if the + nodes don't have identifiers? Then you must determine if the two nodes + have equivalent connections to equivalent nodes all throughout the + whole graph. This is called the graph isomorphism problem. This + algorithm approaches this problem by considering how one might draw + a graph on paper. You can test to see if two nodes are equivalent + by drawing the graph twice. The first time you draw the graph the + first node is drawn in the center of the page. If you can draw the + graph a second time such that it looks just like the first, except + the second node is in the center of the page, then the nodes are + equivalent. This algorithm essentially defines a deterministic way to + draw a graph where, if you begin with a particular node, the graph + will always be drawn the same way. If two graphs are drawn the same way + with two different nodes, then the nodes are equivalent. A + hash is used to indicate a particular way that the graph + has been drawn and can be used to compare nodes.

+ +

When two blank nodes have the same first degree hash, + extra steps must be taken to detect global, + or N-degree, distinctions. + All information that is in any way connected to the blank node n + through other blank nodes, even transitively, must be considered.

+ +

To consider all transitive information, + the algorithm traverses and encodes all possible paths of incident + mentions emanating from n, called gossip paths, + that reach every unlabeled blank node connected to n. + Each unlabeled blank node is assigned a temporary identifier + in the order in which it is reached in the + gossip path being explored. + The mentions that are traversed to reach + connected blank nodes are encoded in these paths via related hashes. + This provides a deterministic way to order all paths coming from n that + reach all blank nodes connected to n without relying on input blank + node identifiers.

+ +

This algorithm works in concert with the main canonicalization algorithm + to produce a unique, deterministic identifier for a particular blank + node. This hash incorporates all of the information that + is connected to the blank node as well as how it is connected. It does + this by creating deterministic paths that emanate out from the blank + node through any other adjacent blank nodes.

+ +

Ultimately, the algorithm selects the shortest gossip path + (based on its encoding as a string), distributing canonical + identifiers to the unlabeled blank nodes in the order in which they + appear in this path. + The hash of this encoded shortest path, + called the N-degree hash of n, + distinguishes n from other blank nodes in the dataset.

+ +

For clarity, we consider a gossip path encoded via the string s + to be shortest provided that:

+ +
    +
  1. The length of s is less than or equal to the length + of any other gossip path string s′.
    2. +
  2. If s and s′ have the same length (as strings), + then s is code point ordered less than or equal to s′.
    3. +
+ +

For example, abc is shorter than bbc, + whereas abcd is longer than bcd.

+ +

The following provides a high level outline for how the N-degree hash of n + is computed along the shortest gossip path. + Note that the full algorithm considers all gossip paths, + ultimately returning the hash of the shortest encoded path.

+ +
    +
  1. Compute related hashes. + Compute the related hash Hn set for n, + i.e., all first degree mentions between n and another blank node. + Note that this includes both unlabeled blank nodes and those + already issued a canonical identifier (labeled blank nodes).
    2. +
  2. Explore mentions. + Given the related hash x in Hn, + record x in the data to hash Dn. + Determine whether each blank node reachable via the mention with related hash x + has already received an identifier. +
      +
    1. Record the identifiers of labeled nodes. + If a blank node already has an identifier, + record its identifier in Dn once for every + mention with related hash x. + Skip to the next related hash in Hn + and repeat step 2.
      2. +
    2. Distribute and record temporary identifiers to unlabeled nodes. + For each unlabeled blank node, + assign it a temporary identifier according to the order in which it is reached in the gossip path, + recording its given identifier in Dn (including repetitions). + Add each unlabeled node to the recursion list Rn(x) + in this same order (omitting repetitions).
      3. +
    3. Recurse on newly labeled nodes. + For each ni in Rn(x) +
        +
      1. Record its identifier in Dn
        2. +
      2. Append < r(i) > to Dn + where r(i) is the data to hash that results from returning to + step 1, + replacing n with ni.
        3. +
      +
      4. +
    +
    3. +
  3. Compute the N-degree hash of n. + Hash Dn to return the N-degree hash of n, + namely hN(n). + Return the updated issuer In + that has now distributed temporary identifiers to all unlabeled blank nodes connected to n.
    4. +
+ +

As described above in step 2.3, + HN recurses on each unlabeled blank node + when it is first reached along the gossip path being explored. + This recursion can be visualized as moving along the path from n + to the blank node ni that is receiving a temporary identifier. + If, when recursing on ni, + another unlabeled blank node nj is discovered, + the algorithm again recurses. + Such a recursion traces out the gossip path from n + to nj via ni.

+ +

The recursive hash r(i) is the hash returned from + the completed recursion on the node ni + when computing hN(n). + Just as hN(n) is the hash of Dn, + we denote the data to hash in the recursion on ni + as Di. + So, r(i) = h(Di). + For each related hash x ∈ Hn, + Rn(x) is called the recursion list on + which the algorithm recurses.

+
+ +

4.8.2 Examples

This section is non-normative.

+ + + +
+ +

4.8.3 Algorithm

+ + +

The inputs to this algorithm are the canonicalization state, + the identifier for the blank node to + recursively hash quads for, and path identifier issuer which is + an identifier issuer that issues temporary + blank node identifiers. The output from this algorithm + will be a hash and the identifier issuer used + to help generate it.

+
+ Logging +

Log the inputs to the algorithm.

+ 
# Inputs for the Hash N-Degree Quads algorithm for double circle example
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+
+ +
    +
  1. Create a new map Hn + for relating hashes to related blank nodes.
    2. +
  2. Get a reference, quads, to the list of quads + from the map entry + for identifier + in the blank node to quads map. +
    + Explanation +

    quads is the mention set of identifier.

    +
    +
    + Logging +

    Log the quads from the mention set of identifier.

    + 
    # Inputs for the Hash N-Degree Quads algorithm for double circle example
+hndq:
+  identifier: e0
+  log point: Hash N-Degree Quads function (4.8.3).
+  issuer: {e0: b0}
+  hndq.2:
+    log point: Quads for identifier (4.8.3 (2)).
+    quads:
+    - _:e0 <http://example.org/vocab#next> _:e1 .
+    - _:e0 <http://example.org/vocab#prev> _:e1 .
+    - _:e1 <http://example.org/vocab#next> _:e0 .
+    - _:e1 <http://example.org/vocab#prev> _:e0 .
+  ...
    +
    +
    3. +
  3. For each quad in quads: +
    + Explanation +

    This loop calculates the related hash Hn + for other blank nodes within the mention set of identifier.

    +
    +
      +
    1. For each component in quad, where component + is the subject, object, or + graph name, and it is a + blank node that is not identified by + identifier: +
        +
      1. Set hash to the result of the + Hash Related Blank Node algorithm, + passing the blank node identifier for + component as related, quad, + issuer, and + position as either s, o, or + g based on whether component is a + subject, object, + graph name, respectively.
        2. +
      2. Add a mapping of hash to the + blank node identifier for component + to Hn, adding an entry + as necessary.
        3. +
      +
      2. +
    +
    + Logging +

    Include the logs for each iteration of the + Hash Related Blank Node algorithm + and the resulting Hn.

    + 
    # Step 3 of Hash N-Degree Quads using double circle example
+hndq:
+  identifier: e0
+  log point: Hash N-Degree Quads function (4.8.3).
+  issuer: {e0: b0}
+  ...
+hndq.3:
+  log point: Hash N-Degree Quads function (4.8.3 (3)).
+  with:
+    - quad: _:e0 <http://example.org/vocab#next> _:e1 .
+      hndq.3.1:
+        log point: Hash related bnode component (4.8.3 (3.1))
+        with:
+          - position: o
+            related: e1
+            h1dq:
+              log point: Hash First Degree Quads function (4.6.3).
+              nquads:
+                - _:z <http://example.org/vocab#next> _:a .
+                - _:z <http://example.org/vocab#prev> _:a .
+                - _:a <http://example.org/vocab#next> _:z .
+                - _:a <http://example.org/vocab#prev> _:z .
+              hash: 60dc8fc7b5481014b6ea38efb05455676d1e93e19b99119ab294941dacc16b3b
+            input: "o<http://example.org/vocab#next>60dc8fc7b5481014b6ea38efb05455676d1e93e19b99119ab294941dacc16b3b"
+            hash: 20bb08971220a5382a9a06ba2977c5fb859e63192e0b2015a378af89e453f25e
+    - quad: _:e0 <http://example.org/vocab#prev> _:e1 .
+      ...
+  Hash to bnodes:
+      20bb08971220a5382a9a06ba2977c5fb859e63192e0b2015a378af89e453f25e:
+        - e1
+      1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d:
+        - e1
+      56d0774755aaf8d9cf4da8af3728e5589f94e5cd7d9aee86f0c5a7bc1d71c7ca:
+        - e1
+      2a5dd448b9467a08479008a5350829441868b7f913343cd500fe8619e047cff4:
+        - e1
+...
    +
    +
    4. +
  4. Create an empty string, data to hash.
    5. +
  5. For each related hash to blank node list mapping in + Hn, code point ordered + by related hash: +
    + Explanation +

    This loop explores the gossip paths for each + related blank node sharing a common hash to identifier + finding the shortest such path (chosen path). + This determines how canonical identifiers for + otherwise commonly hashed blank nodes are chosen. +

    +

    + Each path is represented by the concatenation of the + identifiers for each related blank node + — either the issued identifier, + or a temporary identifier created using a copy of issuer. + Those for which temporary identifiers were issued are later + recursed over using this algorithm. +

    +
    +
    + Logging +

    Log the value of related hash + and state of data to hash.

    + 
    # Log related hash and data to hash in each iteration of step 5 for double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      ...
    +
    +
      +
    1. Append the related hash to the data to hash.
      2. +
    2. Create a string chosen path.
      3. +
    3. Create an unset chosen issuer variable.
      4. +
    4. For each permutation p of blank node list: +
      + Logging +

      Log each permutation p.

      + 
      # Log each permutation of step 5.4 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      hndq.5.4:
+        log point: Hash N-Degree Quads function (4.8.3 (5.4)), entering loop.
+        with:
+        - perm: [ "e1"]
+          ...
      +
      +
        +
      1. Create a copy of issuer, issuer copy.
        2. +
      2. Create a string path.
        3. +
      3. Create a recursion list, to store + blank node identifiers that must be + recursively processed by this algorithm.
        4. +
      4. For each related in p: +
          +
        1. If a canonical identifier has been issued for + related by canonical issuer, append the string _:, followed by + the canonical identifier for related, to path. +
          Explanation +

          A canonical identifier may have been generated before calling this algorithm, + if it was issued from an earlier call to Hash First Degree Quads algorithm. + There is no reason to recurse and apply the algorithm to any related blank node that has already been assigned a canonical identifier. + Furthermore, using the canonical identifier also further distinguishes it from any temporary identifier, allowing for even greater efficiency in finding the chosen path.

          +
          +
          2. +
        2. Otherwise: +
            +
          1. If issuer copy has not issued + an identifier for related, append + related to recursion list. +
            + Explanation +

            Temporarily labeled nodes have identifiers recorded + in issuer copy, + which is later used to recursively call this algorithm, + so that eventually all nodes are given canonical identifiers.

            +
            +
            2. +
          2. Use the + Issue Identifier algorithm, + passing issuer copy and the related, and + append the string _:, followed by the result, to path.
            3. +
          +
          3. +
        3. If chosen path is not empty and the length + of path is greater than or equal to the length + of chosen path and path is + greater than chosen path when + considering code point order, + then skip to the next + permutation p. +
          + Explanation +

          If path is already longer than + the prospective chosen path, + we can terminate this iteration early.

          +
          +
          4. +
        +
        + Explanation +

        path is used to generate a hash at a later step; in this respect, it is similar to + the Hash First Degree Quads algorithm which + uses the serialization of quads in nquads for hashing. For the sake of consistency, the + nquad representation of blank node identifiers is used in these steps, hence the + usage of the _: string.

        +
        +
        + Logging +

        Log related and path.

        + 
        # Log related and path of step 5.4.4 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      hndq.5.4:
+        log point: Hash N-Degree Quads function (4.8.3 (5.4)), entering loop.
+        with:
+        - perm: [ "e1"]
+          hndq.5.4.4:
+            log point: Hash N-Degree Quads function (4.8.3 (5.4.4)), entering loop.
+            with:
+              - related: e1
+                path: ""
+          ...
        +
        +
        5. +
      5. For each related in recursion list: +
        + Explanation +

        The prospective path is extended with + the hash resulting from recursively calling this algorithm + on each related blank node issued a temporary identifier.

        +
        +
        + Logging +

        Log recursion list and path.

        + 
        # Log related and path of step 5.4.5 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      hndq.5.4:
+        log point: Hash N-Degree Quads function (4.8.3 (5.4)), entering loop.
+        with:
+        - perm: [ "e1"]
+          ...
+          hndq.5.4.5:
+            log point: Hash N-Degree Quads function (4.8.3 (5.4.5)), before possible recursion.
+            recursion list: [ "e1"]
+            path: "_:b1"
+          ...
        +
        +
          +
        1. Set result to the result of recursively executing + the Hash N-Degree Quads algorithm, + passing the canonicalization state, + related for identifier, and + issuer copy for path identifier issuer. +
          + Logging +

          Log related and + include logs for each recursive call to Hash N-Degree Quads algorithm.

          + 
          # Log related and path of step 5.4.5.1 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      hndq.5.4:
+        log point: Hash N-Degree Quads function (4.8.3 (5.4)), entering loop.
+        with:
+        - perm: [ "e1"]
+          ...
+          hndq.5.4.5:
+            log point: Hash N-Degree Quads function (4.8.3 (5.4.5)), before possible recursion.
+            recursion list: [ "e1"]
+            path: "_:b1"
+            with:
+              - related: e1
+                hndq:
+                  ...
          +
          +
          2. +
        2. Use the + Issue Identifier algorithm, + passing issuer copy and related; append the string _:, followed by + the result, to path.
          3. +
        3. Append <, the hash in + result, and > to path.
          4. +
        4. Set issuer copy to the + identifier issuer in result.
          5. +
        5. If chosen path is not empty and the length + of path is greater than or equal to the length + of chosen path and path is + greater than chosen path when considering code point order, + then skip to the next p. +
          + Explanation +

          If path is already longer than + the prospective chosen path, + we can terminate this iteration early.

          +
          +
          6. +
        +
        6. +
      6. If chosen path is empty or path is + less than chosen path when considering code point order, + set chosen path to path and chosen issuer + to issuer copy. +
        7. +
      +
      5. +
    5. Append chosen path to data to hash. +
      + Logging +

      Log chosen path and data to hash.

      + 
      # Log chosen path and data to hash logs of step 5.5 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.5:
+    log point: Hash N-Degree Quads function (4.8.3 (5)), entering loop.
+    with:
+    - related_hash: 1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d
+      data_to_hash: ""
+      ...
+      hndq.5.5:
+        log point: Hash N-Degree Quads function (4.8.3 (5.5). End of current loop with Hn hashes.
+        chosen path: "_:b1_:b1<1ae899f76e760eb7caf6656437aaef845b50887aff7baeb3531add85ec02ed35>"
+        data to hash: "1e4e55ba02b8b0b527c32e2343fbcfee2e2bd9c1972c67cc01f85fabde7bc42d_:b1_:b1<1ae899f76e760eb7caf6656437aaef845b50887aff7baeb3531add85ec02ed35>"
+      ...
      +
      +
      6. +
    6. Replace issuer, by reference, withchosen issuer.
      7. +
    +
    6. +
  6. Return issuer and the hash that results from + passing data to hash through the + hash algorithm. +
    + Logging +

    Log issuer and results from passing data to hash + through the hash algorithm.

    + 
    # Log issuer and resulting hash of step 6 using double circle example.
+hndq:
+  log point: Hash N-Degree Quads function (4.8.3).
+  identifier: e0
+  issuer: {e0: b0}
+  ...
+  hndq.6:
+    log point: Leaving Hash N-Degree Quads function (4.8.3).
+    hash: e332b4b59e1c4794ee72a4df0f63723326ffb6d6a5c0d0cb4d2dd8d8d5ebf5a4
+    issuer: {e0: b0, e1: b1}
    +
    +
    7. +
+
+
+
+ +

5. Serialization

+ + +

This section describes the process of creating a serialized [N-Quads] representation + of a canonicalized dataset.

+ +

The serialized canonical form of a canonicalized dataset + is an N-Quads document [N-QUADS] + created by representing each quad from the canonicalized dataset + in canonical n-quads form, + sorting them into code point order, + and concatenating them. (Note that each canonical N-Quads statement ends with a new line, + so no additional separators are needed in the concatenation.) + The resulting document has a media type of application/n-quads, + as described in C. N-Quads Internet Media Type, File Extension and Macintosh File Type + of [N-QUADS].

+ +

When serializing quads in canonical n-quads form, + components which are blank nodes MUST be serialized using the + canonical label associated with each blank node + from the issued identifiers map component of the + canonicalized dataset.

+ + +
+ +

6. Privacy Considerations

This section is non-normative.

+ + +

The nature of the canonicalization algorithm inherently correlates its output, + i.e., the canonical labels and the sorted order of quads, with the input dataset. + This could pose issues, particularly when dealing with datasets containing personal information. + For example, even if certain information is removed from the canonicalized dataset + for some privacy-respecting reason, there remains the possibility that a third party + could infer the omitted data by analyzing the canonicalized dataset. + If it is necessary to decouple the canonicalization algorithm's input and output, + some suitable post-processing methods for the output of the canonicalization should be performed. + This specification has been designed to help make additional processing easier, but + other specifications that build on top of this one are responsible for providing any + specific details. + See Selective Disclosure + in Verifiable Credential Data Integrity 1.0 [VC-DATA-INTEGRITY] for more details about such + post-processing methods. +

+
+ +

7. Security Considerations

This section is non-normative.

+ + +

7.1 Dataset Poisoning

This section is non-normative.

+ + +

The canonicalization algorithm examines every difference in the + information connected to blank nodes in order to ensure that each will + properly receive its own canonical identifier. This process can be + exploited by attackers to construct datasets which are known to take + large amounts of computing time to canonicalize, but that do not express + useful information or express it using unnecessary complexity. + Implementers of the algorithm are expected to add mitigations that will, + by default, abort canonicalizing problematic inputs. +

+

Suggested mitigations include, but are not limited to:

+
    +
  • providing a configurable timeout with a default value applicable to + an implementation's common use
    • +
  • providing a configurable limit on the number of iterations of steps + performed in the algorithm, particularly recursive steps + and permutations of long lists
    • +
+ +

Additionally, software that uses implementations of the algorithm can + employ best-practice schema validation to reject data that does not meet + application requirements, thereby preventing useless poison datasets from + being processed. However, such mitigations are application specific and + not directly applicable to implementers of the canonicalization algorithm + itself. +

+
+ +

7.2 Insecure Hash Algorithms

This section is non-normative.

+ + +

It is possible that the default hash algorithm used by RDFC-1.0 might become + insecure at some point in the future. To mitigate this, this algorithm + and implementations of it can be parameterized to use a different + hash function, without the need to make any changes to the + canonicalization algorithm itself. + However, using a different hash algorithm will generally lead to different results; + applications making use of this specification should carefully weigh the advantages + and disadvantages of using an alternative hash function. +

+ +
Note

The possible implications of the default hash algorithm + becoming insecure are mitigated by that fact that no internal hash + values are revealed, and the canonicalization algorithm is designed to cope + with first-degree hash collisions.

+
+ +
+ +

8. Use Cases

This section is non-normative.

+ +

The use cases that have driven the development of the RDF Dataset Canonicalization algorithm are documented in a separate document. It includes further background and explanations for the design decisions taken [RCH-EXPLAINER].

+
+ +

9. Examples

This section is non-normative.

+ + +

9.1 Duplicate Paths

+ + +

This example illustrates a more complicated example where the same paths + through blank nodes are duplicated in a graph, but use different + blank node identifiers.

+ +
+ + +

+ The image represents the graph described in + + the following code block + .

+ +
Figure 7 An illustration of a graph with duplicated paths.
+ Image available in + + SVG + .
+
+ + 
_:e0 :p1 _:e1 .
+_:e1 :p2 "Foo" .
+_:e2 :p1 _:e3 .
+_:e3 :p2 "Foo" .
+ +

The following is a summary of the more detailed execution log + found here.

+ + +
+ +

9.2 Double Circle

+ + +

This example illustrates another complicated example of + nodes that are doubly connected in opposite directions.

+ +
+ + +

+ The image represents the graph described in + + the following code block + .

+ +
Figure 8 An illustration of a graph back and forth links to nodes.
+ Image available in + + SVG + .
+
+ + 
_:e0 :next _:e1 .
+_:e0 :prev _:e1 .
+_:e1 :next _:e0 .
+_:e1 :prev _:e0 .
+ +

The example is not explored in detail, but the + execution log found here + shows examples of more complicated + pathways through the algorithm

+ +
+ +

9.3 Dataset with Blank Node Named Graph

+ + +

This example illustrates an example of a dataset, + where one graph is named using a blank node, + which is also the object of a triple in the default graph.

+ +
+ + +

+ The image represents the dataset described in + + the following code block + .

+ +
Figure 9 An illustration of a dataset containing a graph named with a blank node.
+ Image available in + + SVG + .
+
+ + 
_:e0 :p1 _:e1 .
+_:e1 :p2 "Foo" .
+_:e1 :p3 _:g0 .
+_:e0 :p1 _:e1 _:g0 .
+_:e1 :p2 "Bar" _:g0 .
+ +

The following is a summary of the more detailed execution log + found here.

+ + +
+
+ +

A. A Canonical form of N-Quads

+ + +

This section defines a canonical form of N-Quads which has + a completely specified layout. + The grammar for the language remains unchanged.

+ +

Canonical N-Quads updates and extends + Canonical N-Triples in [N-TRIPLES] + to include graphLabel.

+ +

While the N-Quads syntax [N-QUADS] allows choices for the representation and layout of RDF data, + the canonical form of N-Quads provides a unique syntactic representation of any quad. + Each code point + can be represented by only one of + UCHAR, + ECHAR, + or unencoded character, + where the relevant production allows for a choice in representation. + Each quad is represented entirely on a single line with specified white space.

+ +

Canonical N-Quads has the following additional constraints on layout:

+
    +
  • White space MUST NOT be used except after + subject, + predicate, + object, + and graphLabel, + each of which MUST be a single space (code point U+0020).
    • +
  • Literals with the + datatype http://www.w3.org/2001/XMLSchema#string + MUST NOT use the datatype IRI part of the literal, + and are represented using only STRING_LITERAL_QUOTE. +
    • +
  • HEX MUST use only digits ([0-9]) and uppercase letters ([A-F]).
    • +
  • Within STRING_LITERAL_QUOTE: +
      +
    • Characters + BS (backspace, code point U+0008), + HT (horizontal tab, code point U+0009), + LF (line feed, code point U+000A), + FF (form feed, code point U+000C), + CR (carriage return, code point U+000D), + " (quotation mark, code point U+0022), and + \ (backslash, code point U+005C) + MUST be encoded using ECHAR.
      • +
    • Characters in the range from U+0000 to U+0007, + VT (vertical tab, code point U+000B), + characters in the range from U+000E to U+001F, + DEL (delete, code point U+007F), + and characters not matching the Char production from [XML11] + MUST be represented by UCHAR + using a lowercase \u with 4 HEXes.
      • +
    • All characters not required to be represented by + ECHAR or + UCHAR + MUST be represented by their native [UNICODE] representation.
      • +
    +
    • +
  • The token EOL MUST be a single LF (line feed, code point U+000A).
    • +
  • The final EOL MUST be provided.
    • +
+
+ +

B. URDNA2015

This section is non-normative.

+ + +

RDF Dataset Canonicalization [CCG-RDC-FINAL] describes + "Universal RDF Dataset Normalization Algorithm 2015" + (URDNA2015), + essentially the same algorithm + as RDFC-1.0, and generally implementations implementing URDNA2015 + should be compatible with this specification. + The minor change is in the canonical n-quads form where + some control characters were previously represented without escaping. + The version of the algorithm defined in A. A Canonical form of N-Quads + clarifies the representation of simple literals and the characters + within STRING_LITERAL_QUOTE + that are encoded using ECHAR.

+
+ +

C. URGNA2012

This section is non-normative.

+ +

A previous version of this algorithm has light deployment. For purposes of identification, + the algorithm is called the + "Universal RDF Graph Canonicalization Algorithm 2012" + (URGNA2012), + and differs from the stated algorithm in the following ways:

+ +
+ +

D. Index

D.1 Terms defined by this specification

+ + +

D.2 Terms defined by reference

+ +
    +
  • + [BCP47] defines the following: +
      +
    • + formatting conventions +
      • +
    +
  • + [INFRA] defines the following: +
      +
    • + boolean type +
    • + entry (for map) +
    • + key (for map) +
    • + list +
    • + map +
    • + string +
      • +
    +
  • + [N-QUADS] defines the following: +
      +
    • + C. N-Quads Internet Media Type, File Extension and Macintosh File Type +
    • + ECHAR +
    • + EOL +
    • + graphLabel +
    • + HEX +
    • + literal +
    • + STRING_LITERAL_QUOTE +
    • + UCHAR +
      • +
    +
  • + [N-TRIPLES] defines the following: +
      +
    • + Canonical N-Triples +
      • +
    +
  • + [RDF11-CONCEPTS] defines the following: +
      +
    • + blank node identifiers +
    • + blank nodes +
    • + Blank Nodes +
    • + default graph +
    • + graph name +
    • + IRIs +
    • + isomorphic datasets +
    • + language tags +
    • + language-tagged strings +
    • + lexical form +
    • + literal +
    • + literal term equality +
    • + literal value +
    • + object type +
    • + predicate +
    • + RDF datasets +
    • + RDF graph +
    • + RDF source +
    • + RDF triple +
    • + Section 3.3 +
    • + simple literals +
    • + Skolem IRIs +
    • + subject +
      • +
    +
  • + [RDF11-MT] defines the following: +
      +
    • + RDF Collections +
      • +
    +
  • + [VC-DATA-INTEGRITY] defines the following: +
      +
    • + Selective Disclosure +
      • +
    +
  • + [XML11] defines the following: +
      +
    • + Char +
      • +
    +
  • + [XPATH-FUNCTIONS] defines the following: +
      +
    • + Unicode code point order +
      • +
    +
    • +
+
+ +

E. Changes since the First Public Working Draft of 24 November 2022

This section is non-normative.

+ +
    +
  • + The algorithm, and the examples, have been changed to systematically + use the xyz format for blank node identifiers, instead of + _:xyz. See Issue 46 + for the discussion. +
    • +
  • + 4.6 Hash First Degree Quads + was simplified to remove the simple flag, + which was unused in existing implementations. + The original design of the algorithm was to use the + assigned canonical blank node identifier, + if available, instead of _:a or _:z, + similar to how it is used in + the related hash algorithm, but this text never made it into the spec + before implementations moved forward. + Therefore, the hashes never change, + making the loop based on the simple + flag that calls this algorithm unnecessary. + See Issue 23 for the discussion. +
    • + +
  • Add definition for canonical n-quads form. Eventually, this should + be a citation from [N-Quads], when it is updated. + Canonical n-quads form is used in 4.6 Hash First Degree Quads. +
    • + +
  • Removed issue marker for + Issue 15 + in 4.4 Canonicalization Algorithm, + adding a note that + literal + components of quads are not normalized, + and two literals with different syntactic representations + remain distinct resources.
    • + +
  • Changed the way Blank Node identifiers are described + (see Issue 46), + generally omitting the leading _: which is a serialization artifact. + This is still required in the algorithms, but the distinction + between what is an identifier, and the serialization form + is clarified.
    • + +
  • Changed the name of the algorithm from URDNA2015 to RDFC-1.0.
    • + +
  • Changed the term normalized dataset to + canonicalized dataset, + which is composed of the input dataset, + input blank node identifier map, and + issued identifiers map.
    • +
+
+ +

F. Changes since the Candidate Recommentation Snapshot of 31 October 2023

This section is non-normative.

+ +
    +
  • + Clarified that detecting a poison dataset will result in an exception and early + termination of the Canonicalization Algorithm. +
    • +
+
+ +

G. Acknowledgements

This section is non-normative.

+ + +

The editors would like to thank Jeremy Carroll for his work on the + graph canonicalization problem, + Andy Seaborne and Gavin Carothers for providing valuable feedback and testing input + for the algorithm defined in this specification, + Sir Tim Berners-Lee for his thoughts on graph canonicalization over the years, + Jesús Arias Fisteus for his work on a similar algorithm, and Aiden Hogan, whose + publication [Hogan-Canonical-RDF] provided an important contemporary + analysis of the canonicalization problem and served as an independent + justification of the development of RDFC-1.0.

+ +

The editors would also like to thank + the chairs of the Working Group, Phil Archer and Markus Sabadello, + and specific members of the Working Group whose active contributions + were critical in completing this work: + Pierre-Antoine Champin, + Ivan Herman, + David Lehn, + Kazue Sako, + Manu Sporny, and + Ted Thibodeau Jr. +

+ +

Members of the RDF Dataset Canonicalization and Hash Working Group Group included Ahamed Azeem, Ahmad Alobaid, Andy Seaborne, Benjamin Goering, Benjamin Young, Brent Zundel, Damien Graux, Dan Brickley, Dan Yamamoto, Daniel Pape, Dave Longley, David Lehn, Duy-Tung Luu, Gregg Kellogg, Ivan Herman, Jean-Yves Rossi, Jennifer Meier, Jesse Wright, Kazue Sako, Leonard Rosenthol, Mahmoud Alkhraishi, Manu Sporny, Markus Sabadello, Michael Prorock, Phil Archer, Pierre-Antoine Champin, Sebastian Crane, Ted Thibodeau Jr, Timothée Haudebourg, and Tobias Kuhn. +

+ +

This specification is based on work done in the + W3C Credentials Community Group + published as [CCG-RDC-FINAL]. + Contributors to the Community Group Final Report include: + Blake Regalia, + Dave Longley, + David Lehn, + David Lozano Jarque, + Gregg Kellogg, + Manu Sporny, + Markus Sabadello, + Matt Collier, and + Sebastian Schmittner. +

+ +

+ Portions of the work on this specification have been funded by the European + Union's StandICT.eu 2023 program under sub-grantee contract numbers No. 08/12 + and 09/25. The + content of this specification does not necessarily reflect the position or the + policy of the European Union and no official endorsement should be inferred. +

+ +

+ Portions of the work on this specification have also been funded by the U.S. + Department of Homeland Security's Silicon Valley Innovation Program under contracts + 70RSAT21T00000020 and 70RSAT23T00000006. The content of this specification does + not necessarily reflect the position or the policy of the U.S. Government and no + official endorsement should be inferred. +

+ +

+ The Working Group acknowledges that the success of this specification is + dependent on a long history of work performed over multiple decades in both + academia and industry. We thank the individuals who iterated on the science + which led to the completion of this specification. A partial list of these + papers is found below, to the best of the Working Group's recollection. + Omission from this list, whether intentional or unintentional, is not meant + to imply that such an unlisted paper was not similarly important to the + development of this work. +

+ + +
+ + + +

H. References

H.1 Normative references

+ +
[FIPS-180-4]
+ FIPS PUB 180-4: Secure Hash Standard (SHS). U.S. Department of Commerce/National Institute of Standards and Technology. August 2015. National Standard. URL: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf +
[INFRA]
+ Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/ +
[N-Quads]
+ RDF 1.1 N-Quads. Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/n-quads/ +
[N-TRIPLES]
+ RDF 1.1 N-Triples. Gavin Carothers; Andy Seaborne. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/n-triples/ +
[RDF11-CONCEPTS]
+ RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/ +
[RFC2119]
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
[RFC3987]
+ Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3987 +
[RFC8174]
+ Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
[Turtle]
+ RDF 1.1 Turtle. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/ +
[UNICODE]
+ The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/ +
[XML11]
+ Extensible Markup Language (XML) 1.1 (Second Edition). Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau; John Cowan et al. W3C. 16 August 2006. W3C Recommendation. URL: https://www.w3.org/TR/xml11/ +
[XPATH-FUNCTIONS]
+ XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition). Ashok Malhotra; Jim Melton; Norman Walsh; Michael Kay. W3C. 14 December 2010. W3C Recommendation. URL: https://www.w3.org/TR/xpath-functions/ +
+

H.2 Informative references

+ +
[BCP47]
+ Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646 +
[CCG-RDC-FINAL]
+ RDF Dataset Canonicalization. Dave Longley. W3C. October 9, 2022. CG-FINAL. URL: https://www.w3.org/community/reports/credentials/CG-FINAL-rdf-dataset-canonicalization-20221009/ +
[DesignIssues-Diff]
+ Delta: an ontology for the distribution of differences between RDF graphs. Tim Berners-Leee. W3C. September 25, 2015. unofficial. URL: https://www.w3.org/DesignIssues/Diff +
[eswc2014Kasten]
+ A Framework for Iterative Signing of Graph Data on the Web. Andreas Kasten; Ansgar Scherp; Peter Schauß . ISWC 2014. 2014. unofficial. URL: https://doi.org/10.1007/978-3-319-07443-6_11 +
[Hogan-Canonical-RDF]
+ Canonical Forms for Isomorphic and Equivalent RDF Graphs: Algorithms for Leaning and Labelling Blank Nodes. Aiden Hogan. ACM. November 2017. ACM Trans. Web 11, 4, Article 22. URL: https://aidanhogan.com/docs/rdf-canonicalisation.pdf +
[HPL-2003-142]
+ Signing RDF Graphs. Jeremy J. Carroll. HP Laboratories Bristol. July 23, 2003. unofficial. URL: https://web.archive.org/web/20230129125726/https://www.hpl.hp.com/techreports/2003/HPL-2003-142.pdf +
[RCH-EXPLAINER]
+ RDF Dataset Canonicalization and Hash Working Group — Explainer and Use Cases. Phil Archer. W3C. 19 October 2023. W3C Working Group Note. URL: https://www.w3.org/TR/rch-explainer/ +
[RDF11-MT]
+ RDF 1.1 Semantics. Patrick Hayes; Peter Patel-Schneider. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-mt/ +
[VC-DATA-INTEGRITY]
+ Verifiable Credential Data Integrity 1.0. Manu Sporny; Dave Longley; Greg Bernstein; Dmitri Zagidulin; Sebastian Crane. W3C. 28 April 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-data-integrity/ +
[YAML]
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html +
+
\ No newline at end of file diff --git a/docs/standards/references/rdf-syntax-grammar.html b/docs/standards/references/rdf-syntax-grammar.html new file mode 100644 index 0000000..c887b91 --- /dev/null +++ b/docs/standards/references/rdf-syntax-grammar.html @@ -0,0 +1,4193 @@ + + + + + RDF 1.1 XML Syntax + + + + + + + + + + +

Abstract

+

This document defines an XML + syntax for RDF called RDF/XML in terms of + Namespaces in XML, the XML Information Set + and XML Base.

+ +

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

This document is an edited version of the 2004 RDF XML Syntax + Specification Recommendation. The purpose of this revision is + to make this + document available as part of the RDF 1.1 document set. Changes are + limited to revised references, terminology updates, and adaptations to + the introduction. + The technical content of the document is unchanged, except for + the fact that the datatype XMLLiiteral is marked as + non-normative in RDF 1.1. The (non-normative) algorithm for + parsing XMLLiteral + (Sec. 7.2.17) + has been updated to be in line with + the current state of XML technology. Details of the changes + are listed in the Changes + section. Since the edits to this document do not invalidate + previous implementations the Director decided no new implementation report was required.

+ +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + +
+ + +

1. Introduction

+ +

This document defines the + XML [XML10] syntax for RDF graphs.

+ +

This document revises the original RDF/XML grammar [RDFMS] + in terms of XML Information Set [XML-INFOSET] information items which moves + away from the rather low-level details of XML, such as particular + forms of empty elements. This allows the grammar to be more + precisely recorded and the mapping from the XML syntax to the RDF + Graph more clearly shown. The mapping to the RDF graph is done by + emitting statements in the N-Triples [N-TRIPLES] format.

+ +

This document is part of the suite of RDF 1.1 + documents. Other documents in this suite are:

+ +
    +
  • A document describing the basic concepts underlying RDF, as + well as abstract syntax ("RDF Concepts and Abstract Syntax") + [RDF11-CONCEPTS]
    • +
  • A document describing the formal model-theoretic semantics + of RDF ("RDF Semantics") [RDF11-MT]
    • +
  • Specifications of concrete syntaxes for RDF: +
      +
    • Turtle [TURTLE] and TriG [TRIG]
      • +
    • JSON-LD [JSON-LD] (JSON based)
      • +
    • RDFa [RDFA-PRIMER] (for HTML embedding)
      • +
    • N-Triples and N-Quads (line-based exchange formats)
      • +
    • +
  • A document describing RDF Schema [RDF11-SCHEMA], which + provides a data-modeling vocabulary for RDF data.
    • +
+

For a longer introduction to the RDF/XML syntax with a historical + perspective, see "RDF: Understanding the Striped RDF/XML + Syntax" [STRIPEDRDF].

+ +
+ + + + + + +
+ + + +

2. An XML Syntax for RDF

+

This section introduces the RDF/XML syntax, describes how it + encodes RDF graphs and explains this with examples. If there is any + conflict between this informal description and the formal description + of the syntax and grammar in sections + 6 Syntax Data Model and + 7 RDF/XML Grammar, the + latter two sections take precedence. +

+ + + + +
+

2.1 Introduction

+ +

The RDF Concepts and Abstract Syntax document [RDF11-CONCEPTS] + defines the RDF Graph data model and the + RDF Graph abstract syntax. + Along with the RDF Semantics [RDF11-MT] + this provides an abstract syntax with a formal semantics for it. + The RDF graph has nodes + and labeled directed arcs + that link pairs of nodes and this is represented as a set of + RDF triples + where each triple contains a + subject node, predicate and object node. + Nodes are IRIs, literals, or blank nodes. + Blank nodes may be given + a document-local identifier called a + blank node identifier. + Predicates are IRIs + and can be interpreted as either a relationship between the two + nodes or as defining an attribute value (object node) for some + subject node.

+ +

In order to encode the graph in XML, the nodes and predicates have to be + represented in XML terms — element names, attribute names, element contents + and attribute values. + RDF/XML uses XML + QNames + as defined in Namespaces in XML [XML-NAMES] to represent IRIs. + All QNames have a namespace + name which is an IRI + and a short + local name. + In addition, QNames can either have a short + prefix + or be declared with the default namespace declaration and have none (but + still have a namespace name)

+ +

The IRI represented by a QName is determined by appending the + local name + part of the QName after the + namespace + name (IRI) part of the QName. + This is used to shorten the IRI + of all predicates and some nodes. + IRIs identifying + subject and object nodes can also be stored as XML attribute values. + RDF literals + which can only be object nodes, + become either XML element text content or XML attribute values.

+ +

A graph can be considered a collection of paths of the form node, + predicate arc, node, predicate arc, node, predicate arc, ... node + which cover the entire graph. In RDF/XML these turn into sequences of + elements inside elements which alternate between elements for nodes + and predicate arcs. This has been called a series of node/arc + stripes. The node at the start of the sequence turns into the + outermost element, the next predicate arc turns into a child element, + and so on. The stripes generally start at the top of an RDF/XML + document and always begin with nodes. +

+ +

Several RDF/XML examples are given in the following sections + building up to complete RDF/XML documents. Example 7 + is the first complete RDF/XML document.

+
+ + + + + +
+

2.2 Node Elements and Property Elements

+ + +
+ Graph for RDF/XML Example +
Fig. 1 Graph for RDF/XML Example (SVG version)
+
+ +

An RDF graph is given in Figure 1 + where the nodes are represented as ovals and contain their + IRIs where they have them, all the predicate arcs are labeled with + IRIs and string literals nodes have been written in rectangles.

+ + +

If we follow one node, predicate arc ... , node path through the + graph shown in Figure 2: +

+ +
+ One Path Through the Graph +
Fig. 2 One Path Through the Graph (SVG version)
+
+ +

The left hand side of the Figure 2 + graph corresponds to the node/predicate arc stripes:

+ +
    + +
  1. Node with IRI http://www.w3.org/TR/rdf-syntax-grammar
    2. +
  2. Predicate Arc labeled with IRI http://example.org/terms/editor
    3. +
  3. Node with no IRI
    4. +
  4. Predicate Arc labeled with IRI http://example.org/terms/homePage
    5. + +
  5. Node with IRI http://purl.org/net/dajobe/
    6. +
+ +

In RDF/XML, the sequence of 5 nodes and predicate arcs on + the left hand side of Figure 2 corresponds to + the usage of five XML elements of two types, for the graph nodes and + predicate arcs. These are conventionally called node elements and + property elements respectively. In the striping shown in + + Example 1, rdf:Description is the + node element (used three times for the three nodes) and + ex:editor and ex:homePage are the two + property elements. +

+ +
Example 1
Striped RDF/XML (nodes and predicate arcs)
+	
+<rdf:Description>
+  <ex:editor>
+    <rdf:Description>
+      <ex:homePage>
+        <rdf:Description>
+        </rdf:Description>
+      </ex:homePage>
+    </rdf:Description>
+  </ex:editor>
+</rdf:Description>
+ +

The Figure 2 graph consists of some nodes + that are + IRIs + + (and others that are not) and this can be added + to the RDF/XML using the rdf:about attribute on node + elements to give the result in Example 2:

+ +
Example 2
Node Elements with IRIs added
+	
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <ex:editor>
+    <rdf:Description>
+      <ex:homePage>
+        <rdf:Description rdf:about="http://purl.org/net/dajobe/">
+        </rdf:Description>
+      </ex:homePage>
+    </rdf:Description>
+  </ex:editor>
+</rdf:Description>
+ +

Adding the other two paths through the Figure 1 + graph to the RDF/XML in + Example 2 + gives the result in Example 3 + (this example fails to show that the blank node is + shared between the two paths, see + 2.10):

+ +
Example 3
Complete description of all graph paths
+
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <ex:editor>
+    <rdf:Description>
+      <ex:homePage>
+        <rdf:Description rdf:about="http://purl.org/net/dajobe/">
+        </rdf:Description>
+      </ex:homePage>
+    </rdf:Description>
+  </ex:editor>
+</rdf:Description>
+
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <ex:editor>
+    <rdf:Description>
+      <ex:fullName>Dave Beckett</ex:fullName>
+    </rdf:Description>
+  </ex:editor>
+</rdf:Description>
+
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <dc:title>RDF 1.1 XML Syntax</dc:title>
+</rdf:Description>
+ +
+ + + + +
+

2.3 Multiple Property Elements

+ +

There are several abbreviations that can be used to make common + uses easier to write down. In particular, it is common that a + subject node in the RDF graph has multiple outgoing predicate arcs. RDF/XML + provides an abbreviation for the corresponding syntax when a node + element about a resource has multiple property elements. This can be + abbreviated by using multiple child property elements inside the node + element describing the subject node.

+ +

Taking Example 3, there are + two node elements that can take multiple property elements. + The subject node with IRI + http://www.w3.org/TR/rdf-syntax-grammar + has property elements ex:editor and ex:title + + and the node element for the blank node can take ex:homePage + and ex:fullName. This abbreviation + gives the result shown in Example 4 + (this example does show that there is a single blank node):

+ +
Example 4
Using multiple property elements on a node element
+	  
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <ex:editor>
+    <rdf:Description>
+      <ex:homePage>
+        <rdf:Description rdf:about="http://purl.org/net/dajobe/">
+        </rdf:Description>
+      </ex:homePage>
+      <ex:fullName>Dave Beckett</ex:fullName>
+    </rdf:Description>
+  </ex:editor>
+  <dc:title>RDF 1.1 XML Syntax</dc:title>
+</rdf:Description>
+ +
+ + + + +
+

2.4 Empty Property Elements

+ +

When a predicate arc in an RDF graph points to an object node which has no + further predicate arcs, which appears in RDF/XML as an empty node element + <rdf:Description rdf:about="..."> + </rdf:Description> + (or <rdf:Description rdf:about="..." />) + this form can be shortened. This is done by using the + IRI of the object node as the value of an XML attribute rdf:resource + on the containing property element and making the property element empty. +

+ +

In this example, the property element ex:homePage + contains an empty node element with the + IRI + http://purl.org/net/dajobe/. This can be replaced with + the empty property element form giving the result shown in + Example 5:

+ +
Example 5
Empty property elements
+	  
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+  <ex:editor>
+    <rdf:Description>
+      <ex:homePage rdf:resource="http://purl.org/net/dajobe/"/>
+      <ex:fullName>Dave Beckett</ex:fullName>
+    </rdf:Description>
+  </ex:editor>
+  <dc:title>RDF 1.1 XML Syntax</dc:title>
+</rdf:Description>
+ +
+ + + + +
+

2.5 Property Attributes

+ +

When a property element's content is string literal, + it may be possible to use it as an XML attribute on the + containing node element. + This can be done for multiple properties on the same node element + only if the property element name is not repeated + (required by XML — attribute names are unique on an XML element) + and any in-scope xml:lang on the + property element's string literal (if any) are the same (see + Section 2.7) + This abbreviation is known as a Property Attribute + and can be applied to any node element.

+ +

This abbreviation can also be used when the property element is + rdf:type and it has an rdf:resource attribute + the value of which is interpreted as a + IRI object node.

+ +

In Example 5:, + there are two property elements with string literal content, + the dc:title and ex:fullName + property elements. These can be replaced with property attributes + giving the result shown in Example 6:

+ +
Example 6
Replacing property elements with string literal content into property attributes
+	  
+<rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
+           dc:title="RDF 1.1 XML Syntax">
+  <ex:editor>
+    <rdf:Description ex:fullName="Dave Beckett">
+      <ex:homePage rdf:resource="http://purl.org/net/dajobe/"/>
+    </rdf:Description>
+  </ex:editor>
+</rdf:Description>
+ +
+ + + + +
+

2.6 Completing the Document: Document Element and XML Declaration

+ +

To create a complete RDF/XML document, the serialization of the + graph into XML is usually contained inside an rdf:RDF + XML element which becomes the top-level XML document element. + Conventionally the rdf:RDF element is also used to + declare the XML namespaces that are used, although that is not + required. When there is only one top-level node element inside + rdf:RDF, the rdf:RDF can be omitted + although any XML namespaces must still be declared.

+ +

The XML specification also permits an XML declaration at + the top of the document with the XML version and possibly the XML + content encoding. This is optional but recommended.

+ +

Completing the RDF/XML could be done for any of the correct + complete graph examples from + Example 4 onwards but taking the smallest + Example 6 and adding the final components, + gives a complete RDF/XML representation of the original + Figure 1 graph + in Example 7:

+ +
Example 7
Complete RDF/XML description of Figure 1 graph 
+(example07.rdf, output example07.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
+             dc:title="RDF1.1 XML Syntax">
+    <ex:editor>
+      <rdf:Description ex:fullName="Dave Beckett">
+        <ex:homePage rdf:resource="http://purl.org/net/dajobe/" />
+      </rdf:Description>
+    </ex:editor>
+  </rdf:Description>
+
+</rdf:RDF>
+ +

It is possible to omit rdf:RDF in + Example 7 above since there is only one + rdf:Description inside rdf:RDF but this + is not shown here.

+
+ + + + +
+

2.7 Languages: xml:lang

+ +

RDF/XML permits the use of the xml:lang attribute as defined by + 2.12 Language Identification + of XML 1.0 [XML10] + to allow the identification of content language. + The xml:lang attribute can be used on any node element or property element + to indicate that the included content is in the given language. + Typed literals + which includes XML literals + are not affected by this attribute. + The most specific in-scope language present + (if any) is applied to property element string literal content or + property attribute values. The xml:lang="" form + indicates the absence of a language identifier.

+ +

Some examples of marking content languages for RDF properties are shown in + Example 8:

+ +
Example 8
Complete example of xml:lang
+(example08.rdf, output example08.nt)
+
+<?xml version="1.0" encoding="utf-8"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/">
+
+  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar">
+    <dc:title>RDF 1.1 XML Syntax</dc:title>
+    <dc:title xml:lang="en">RDF 1.1 XML Syntax</dc:title>
+    <dc:title xml:lang="en-US">RDF 1.1 XML Syntax</dc:title>
+  </rdf:Description>
+
+  <rdf:Description rdf:about="http://example.org/buecher/baum" xml:lang="de">
+    <dc:title>Der Baum</dc:title>
+    <dc:description>Das Buch ist außergewöhnlich</dc:description>
+    <dc:title xml:lang="en">The Tree</dc:title>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.8 XML Literals: rdf:parseType="Literal"

This section is non-normative.

+ +

RDF allows XML literals [RDF11-CONCEPTS] + to be given as the object node of a predicate. + These are written in RDF/XML as content of a property element (not + a property attribute) and indicated using the + rdf:parseType="Literal" attribute on the containing + property element. +

+ +

An example of writing an XML literal is given in + Example 9 where + there is a single RDF triple with the subject node + IRI + http://example.org/item01, the predicate + IRI + http://example.org/stuff/1.0/prop (from + ex:prop) and the object node with XML literal + content beginning a:Box. +

+ +
Example 9
Complete example of rdf:parseType="Literal"
+(example09.rdf, output example09.nt)
+	  
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://example.org/item01"> 
+    <ex:prop rdf:parseType="Literal" xmlns:a="http://example.org/a#">
+      <a:Box required="true">
+        <a:widget size="10" />
+        <a:grommit id="23" />
+      </a:Box>
+    </ex:prop>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.9 Typed Literals: rdf:datatype

+ +

RDF allows typed literals + to be given as the object node of a predicate. Typed literals consist of a literal + string and a datatype + IRI. These are written in RDF/XML using + the same syntax for literal string nodes in the property element form + (not property attribute) but with an additional + rdf:datatype="datatypeURI" + attribute on the property element. Any + IRI can be used in the attribute. +

+ +

An example of an RDF typed + literal + is given in Example 10 where + there is a single RDF triple with the subject node + IRI + http://example.org/item01, the predicate + IRI + http://example.org/stuff/1.0/size (from + ex:size) and the object node with the + typed literal + ("123", http://www.w3.org/2001/XMLSchema#int) + to be interpreted as an + XML Schema [XMLSCHEMA-2] datatype int. +

+ +
Example 10
Complete example of rdf:datatype
+(example10.rdf,  output example10.nt)
+	  
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://example.org/item01">
+    <ex:size rdf:datatype="http://www.w3.org/2001/XMLSchema#int">123</ex:size>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.10 Identifying Blank Nodes: rdf:nodeID

+ +

Blank nodes in the RDF graph are distinct but have no + IRI identifier. + It is sometimes required that the same graph blank node is referred to in the + RDF/XML in multiple places, such as at the subject and object + of several RDF triples. In this case, a blank node identifier + can be given to the blank node for identifying it + in the document. Blank node identifiers in RDF/XML are scoped to the + containing XML Information Set + document information item. + A blank node identifier is used + on a node element to replace + rdf:about="IRI" + or on a property element to replace + rdf:resource="IRI" + + with rdf:nodeID="blank node identifier" + in both cases.

+ +

Taking Example 7 and explicitly giving + a blank node identifier of abc to the blank node in it + gives the result shown in Example 11. + The second rdf:Description property element is + about the blank node.

+ + +
Example 11
Complete RDF/XML description of graph using rdf:nodeID identifying the blank node
+(example11.rdf,  output example11.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
+             dc:title="RDF 1.1 XML Syntax">
+    <ex:editor rdf:nodeID="abc"/>
+  </rdf:Description>
+
+  <rdf:Description rdf:nodeID="abc" ex:fullName="Dave Beckett">
+    <ex:homePage rdf:resource="http://purl.org/net/dajobe/"/>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.11 Omitting Blank Nodes: rdf:parseType="Resource"

+ +

Blank nodes (not IRI nodes) in RDF graphs can be written + in a form that allows the + <rdf:Description> + </rdf:Description> pair to be omitted. + The omission is done by putting an + rdf:parseType="Resource" + attribute on the containing property element + that turns the property element into a property-and-node element, + which can itself have both property elements and property attributes. + Property attributes and the rdf:nodeID attribute + are not permitted on property-and-node elements. + +

+ +

Taking the earlier Example 7, + the contents of the ex:editor property element + could be alternatively done in this fashion to give + the form shown in Example 12:

+ +
Example 12
Complete example using rdf:parseType="Resource"
+(example12.rdf, output: example12.nt)
+	  
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
+                   dc:title="RDF 1.1 XML Syntax">
+    <ex:editor rdf:parseType="Resource">
+      <ex:fullName>Dave Beckett</ex:fullName>
+      <ex:homePage rdf:resource="http://purl.org/net/dajobe/"/>
+    </ex:editor>
+  </rdf:Description>
+</rdf:RDF>
+ +
+ + + + +
+

2.12 Omitting Nodes: Property Attributes on an empty Property Element

+ +

If all of the property elements on a blank node element have + string literal values with the same in-scope xml:lang + value (if present) and each of these property elements appears at + most once and there is at most one rdf:type property + element with a IRI object node, these can be abbreviated by + moving them to be property attributes on the containing property + element which is made an empty element.

+ +

Taking the earlier Example 5, + the ex:editor property element contains a + blank node element with two property elements + + ex:fullname and ex:homePage. + ex:homePage is not suitable here since it + does not have a string literal value, so it is being + ignored for the purposes of this example. + The abbreviated form removes the ex:fullName property element + and adds a new property attribute ex:fullName with the + string literal value of the deleted property element + to the ex:editor property element. + The blank node element becomes implicit in the now empty + + ex:editor property element. The result is shown in + Example 13.

+ +
Example 13
Complete example of property attributes on an empty property element
+(example13.rdf, output example13.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
+            dc:title="RDF 1.1 XML Syntax">
+    <ex:editor ex:fullName="Dave Beckett" />
+            <!-- Note the ex:homePage property has been ignored for this example -->
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.13 Typed Node Elements

+ +

It is common for RDF graphs to have rdf:type predicates + from subject nodes. These are conventionally called typed + nodes in the graph, or typed node elements in the + RDF/XML. RDF/XML allows this triple to be expressed more concisely. + by replacing the rdf:Description node element name with + the namespaced-element corresponding to the + + IRI of the value of + the type relationship. There may, of course, be multiple rdf:type + predicates but only one can be used in this way, the others must remain as + property elements or property attributes. +

+ +

The typed node elements are commonly used in RDF/XML with the built-in + classes in the RDF vocabulary: + rdf:Seq, rdf:Bag, rdf:Alt, + + rdf:Statement, rdf:Property and + rdf:List.

+ +

For example, the RDF/XML in Example 14 + could be written as shown in Example 15.

+ +
Example 14
Complete example with rdf:type
+(example14.rdf, output example14.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://example.org/thing">
+    <rdf:type rdf:resource="http://example.org/stuff/1.0/Document"/>
+    <dc:title>A marvelous thing</dc:title>
+  </rdf:Description>
+</rdf:RDF>
+ +
Example 15
Complete example using a typed node element to replace an rdf:type
+(example15.rdf, output example15.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:dc="http://purl.org/dc/elements/1.1/"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <ex:Document rdf:about="http://example.org/thing">
+    <dc:title>A marvelous thing</dc:title>
+  </ex:Document>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.14 Abbreviating URIs: rdf:ID and xml:base

+ +

RDF/XML allows further abbreviating IRIs in XML attributes in two + ways. The XML Infoset provides a base URI attribute xml:base + that sets the base URI for resolving relative IRIs, otherwise + the base URI is that of the document. The base URI applies to + all RDF/XML attributes that deal with IRIs which are rdf:about, + rdf:resource, rdf:ID + and rdf:datatype.

+ +

The rdf:ID attribute on a node element (not property + element, that has another meaning) can be used instead of + rdf:about and gives a relative IRI equivalent to # + concatenated with the rdf:ID attribute value. So for + example if rdf:ID="name", that would be equivalent + to rdf:about="#name". rdf:ID provides an additional + check since the same name can only appear once in the + scope of an xml:base value (or document, if none is given), + so is useful for defining a set of distinct, + related terms relative to the same IRI.

+ +

Both forms require a base URI to be known, either from an in-scope + xml:base or from the URI of the RDF/XML document.

+ +

Example 16 shows abbreviating the node + IRI of http://example.org/here/#snack using an + xml:base of http://example.org/here/ and + an rdf:ID on the rdf:Description node element. + The object node of the ex:prop predicate is an + absolute IRI + + resolved from the rdf:resource XML attribute value + using the in-scope base URI to give the + IRI http://example.org/here/fruit/apple.

+ +
Example 16
Complete example using rdf:ID and xml:base for shortening URIs
+(example16.rdf, output example16.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:ex="http://example.org/stuff/1.0/"
+            xml:base="http://example.org/here/">
+
+  <rdf:Description rdf:ID="snack">
+    <ex:prop rdf:resource="fruit/apple"/>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.15 Container Membership Property Elements: rdf:li and rdf:_n

+ +

RDF has a set of container membership properties + and corresponding property elements that are mostly used with + instances of the + rdf:Seq, rdf:Bag and rdf:Alt + + classes which may be written as typed node elements. The list properties are + rdf:_1, rdf:_2 etc. and can be written + as property elements or property attributes as shown in + Example 17. There is an rdf:li + special property element that is equivalent to + rdf:_1, rdf:_2 in order, + explained in detail in section 7.4. + The mapping to the container membership properties is + always done in the order that the rdf:li special + property elements appear in XML — the document order is significant. + The equivalent RDF/XML to Example 17 written + in this form is shown in Example 18. +

+ +
Example 17
Complex example using RDF list properties
+(example17.rdf, output example17.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+
+  <rdf:Seq rdf:about="http://example.org/favourite-fruit">
+    <rdf:_1 rdf:resource="http://example.org/banana"/>
+    <rdf:_2 rdf:resource="http://example.org/apple"/>
+    <rdf:_3 rdf:resource="http://example.org/pear"/>
+  </rdf:Seq>
+
+</rdf:RDF>
+ +
Example 18
Complete example using rdf:li property element for list properties
+(example18.rdf, output example18.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+
+  <rdf:Seq rdf:about="http://example.org/favourite-fruit">
+    <rdf:li rdf:resource="http://example.org/banana"/>
+    <rdf:li rdf:resource="http://example.org/apple"/>
+    <rdf:li rdf:resource="http://example.org/pear"/>
+  </rdf:Seq>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.16 Collections: rdf:parseType="Collection"

+ +

RDF/XML allows an rdf:parseType="Collection" + + attribute on a property element to let it contain multiple node + elements. These contained node elements give the set of subject + nodes of the collection. This syntax form corresponds to a set of + triples connecting the collection of subject nodes, the exact triples + generated are described in detail in + Section 7.2.19 Production parseTypeCollectionPropertyElt. + The collection construction is always done in the order that the node + elements appear in the XML document. Whether the order of the + collection of nodes is significant is an application issue and not + defined here. +

+ +

Example 19 shows a collection of three + nodes elements at the end of the ex:hasFruit + property element using this form.

+ +
Example 19
Complete example of a RDF collection of nodes using rdf:parseType="Collection"
+(example19.rdf, output example19.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:ex="http://example.org/stuff/1.0/">
+
+  <rdf:Description rdf:about="http://example.org/basket">
+    <ex:hasFruit rdf:parseType="Collection">
+      <rdf:Description rdf:about="http://example.org/banana"/>
+      <rdf:Description rdf:about="http://example.org/apple"/>
+      <rdf:Description rdf:about="http://example.org/pear"/>
+    </ex:hasFruit>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ + + + +
+

2.17 Reifying Statements: rdf:ID

+ +

The rdf:ID attribute can be used on a property + element to reify the triple that it generates (See + section 7.3 Reification Rules for the + full details). + The identifier for the triple should be constructed as a + IRI + made from the relative IRI + # concatenated with the rdf:ID attribute + value, resolved against the in-scope base URI. So for example if + + rdf:ID="triple", that would be equivalent to the IRI + formed from relative IRI #triple against the base URI. + Each (rdf:ID attribute value, base URI) + pair has to be unique in an RDF/XML document, + see constraint-id. +

+ +

Example 20 shows a rdf:ID + being used to reify a triple made from the ex:prop + property element giving the reified triple the + IRI http://example.org/triples/#triple1.

+ +
Example 20
Complete example of rdf:ID reifying a property element
+(example20.rdf, output example20.nt)
+
+<?xml version="1.0"?>
+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+            xmlns:ex="http://example.org/stuff/1.0/"
+            xml:base="http://example.org/triples/">
+  <rdf:Description rdf:about="http://example.org/">
+    <ex:prop rdf:ID="triple1">blah</ex:prop>
+  </rdf:Description>
+
+</rdf:RDF>
+ +
+ +
+ + + + + + +
+ + +

3. Terminology

+ +

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in + this document are to be interpreted as described in + RFC 2119 [RFC2119].

+ +

All use of string without further qualification refers to + a Unicode [UNICODE] character string; + a sequence of characters represented by a code point in + Unicode. + +

+ + + + + + +
+ + +

4. RDF MIME Type, File Extension and Macintosh File Type

+ +

The Internet media type / MIME type for RDF/XML is + application/rdf+xml — + RFC 3023 [RFC3023], section 8.18. +

+ +
Note

(Informative): + For the state of the MIME type registration, consult + IANA MIME Media Types [IANA-MEDIA-TYPES] +

+ +

It is recommended that RDF/XML files have the extension + ".rdf" (all lowercase) on all platforms.

+ +

It is recommended that RDF/XML files stored on Macintosh HFS file + systems be given a file type of "rdf " + (all lowercase, with a space character as the fourth letter).

+
+ + + + + + +
+ + +

5. Global Issues

+ + + + +
+ +

5.1 The RDF Namespace and Vocabulary

+ +

The RDF namespace IRI (or namespace name) is + http://www.w3.org/1999/02/22-rdf-syntax-ns# + and is typically used in XML with the prefix rdf + although other prefix strings may be used. + The RDF Vocabulary + is identified by this namespace name and consists of the following names only:

+ +
+
Syntax names — not concepts
+
+

+ RDF Description ID about parseType resource li nodeID datatype +

+
+ +
Class names
+
+

+ Seq Bag Alt Statement Property XMLLiteral List +

+
+ +
Property names
+
+

+ subject predicate object type value first rest _n
+ where n is a decimal integer greater than zero with no leading zeros. +

+
+ +
Resource names
+
+

+ nil +

+
+ +
+ +

Any other names are not defined and SHOULD generate a warning when + encountered, but should otherwise behave normally.

+ +

Within RDF/XML documents it is not permitted to use XML namespaces + whose namespace name is the + ·RDF namespace IRI· + + concatenated with additional characters.

+ +

Throughout this document the terminology rdf:name + will be used to indicate name is from the RDF vocabulary + and it has a IRI of the concatenation of the + ·RDF namespace IRI· and name. + For example, rdf:type has the IRI + http://www.w3.org/1999/02/22-rdf-syntax-ns#type

+
+ + + + + +
+

5.2 Identifiers

+ +

The RDF Concepts document [RDF11-CONCEPTS] + defines the three types of RDF data that can act as node + and/or predicate:

+ +
+ +
IRI
+
+

IRIs can act as node (both subject and object) and as + predicate.

+ +

IRIs + can be either:

+
    +
  • given as XML attribute values interpreted as relative + IRIs that are resolved against the in-scope base URI + as described in section 5.3 + to give absolute IRIs
    • +
  • transformed from XML namespace-qualified element and attribute names + (QNames)
    • +
  • transformed from rdf:ID attribute values.
    • +
+ +

Within RDF/XML, XML QNames are transformed into + IRIs + by appending the XML local name to the namespace name (IRI). + For example, if the XML namespace prefix foo has + namespace name (IRI) + + http://example.org/somewhere/ then the QName + foo:bar would correspond to the IRI + http://example.org/somewhere/bar. Note that this + restricts which + IRIs can be made and the same IRI can be given in multiple ways.

+ +

The rdf:ID values + are transformed into + IRIs + by appending the attribute value to the result of appending + "#" to the in-scope base URI which is defined in + Section 5.3 Resolving IRIs

+
+ +
Literal
+
+

Literals can only act as object nodes.

+ +

Literals + always have a datatype. Language-tagged strings get + the datatype rdf:langString. When there is no + language tag or datatype specified the literal is assumed to have the datatype + xsd:string.

+
+ +
Blank Node
+
+

Blank nodes can act as subject node and as object node.

+ +

Blank nodes + have distinct identity in the RDF graph. + When the graph is written in a syntax such as RDF/XML, these + blank nodes may need graph-local identifiers and a syntax + in order to preserve this distinction. These local identifiers are called + blank node identifiers + and are used in RDF/XML as values of the rdf:nodeID attribute + with the syntax given in Production nodeIdAttr. + Blank node identifiers in RDF/XML are scoped to the XML Information Set + document information item.

+ +

If no blank node identifier is given explicitly as an + rdf:nodeID attribute value then one will need to be + generated (using generated-blank-node-id, see section 6.3.3). + Such generated blank node + identifiers must not clash with any blank node identifiers derived + from rdf:nodeID attribute values. This can be + implemented by any method that preserves the distinct identity of all + the blank nodes in the graph, that is, the same blank node identifier + is not given for different blank nodes. One possible method would be + to add a constant prefix to all the rdf:nodeID attribute + values and ensure no generated blank node identifiers ever used that + prefix. Another would be to map all rdf:nodeID attribute + values to new generated blank node identifiers and perform that mapping + on all such values in the RDF/XML document.

+
+
+ +
+ + + + + +
+

5.3 Resolving IRIs

+ +

RDF/XML supports + XML Base [XMLBASE] + which defines a + ·base-uri· + accessor for each ·root event· and + ·element event·. + Relative IRIs are resolved into + IRIs + according to the algorithm specified in [XMLBASE] (and RFC 2396). + These specifications do not specify an algorithm for resolving a + fragment identifier alone, such as #foo, or the empty + string "" into an + IRI. In RDF/XML, a fragment identifier + is transformed into an IRI + by appending the fragment identifier to the in-scope base URI. The + empty string is transformed + into an IRI by substituting the in-scope base URI. +

+ +
Note

Test: + indicated by:
+ test001.rdf and + test001.nt +
+ test004.rdf and + test004.nt +
+ test008.rdf and + test008.nt +

+ +

An empty same document reference "" + resolves against the URI part of the base URI; any fragment part + is ignored. See + Uniform Resource Identifiers (URI) [RFC3986]. +

+ +
Note

Test: + Indicated by + test013.rdf and + test013.nt +

+ +
Note

Implementation Note (Informative): + When using a hierarchical base + URI that has no path component (/), it must be added before using as a + base URI for resolving. +

+ +
Note

Test: + Indicated by + test011.rdf and + test011.nt +

+
+ + + + + +
+

5.4 Constraints

+ +
+
constraint-id
+

Each application of production idAttr + matches an attribute. The pair formed by the + ·string-value· + accessor of the matched attribute and the + ·base-uri· + accessor of the matched attribute is unique within a single RDF/XML + document.

+ +

The syntax of the names must match the + rdf-id production.

+ +
Note

Test: + Indicated by + test014.rdf and + test014.nt +

+
+ +
+
+ + + + + +
+

5.5 Conformance

+ +
+
Definition:
+
An RDF Document is a serialization of an + RDF Graph + into a concrete syntax.
+ +
Definition:
+
An RDF/XML Document is an + RDF Document written in the + XML syntax for RDF as defined in this document.
+ +
Conformance:
+
An RDF/XML Document is a + conforming RDF/XML document + if it adheres to the specification defined in this document.
+
+
+ +
+ + + + + + +
+ + + +

6. Syntax Data Model

+ +
+

This document specifies the syntax of RDF/XML as a grammar on an + alphabet of symbols. The symbols are called events in the + style of the XPATH   + Information Set Mapping. + A sequence of events is normally derived from an XML document, in + which case they are in document order as defined below in + Section 6.2 Information Set Mapping. + The sequence these events form are intended to be similar to the sequence + of events produced by the [SAX] XML API from + the same XML document. Sequences of events may be checked against + the grammar to determine whether they are or are not syntactically + well-formed RDF/XML.

+ +

The grammar productions may include actions which fire when the + production is recognized. Taken together these actions define a + transformation from any syntactically well-formed RDF/XML sequence of + events into an RDF graph represented in the N-Triples [N-TRIPLES] + language.

+ +

The model given here illustrates one way to create a representation of + an RDF Graph + from an RDF/XML document. It does not mandate any implementation + method — any other method that results in a representation of the same + RDF Graph may be used.

+ +

In particular:

+
    +
  • This specification permits any + representation of an RDF graph; + in particular, it does not require the use of N-Triples [N-TRIPLES].
    • +
  • This specification does not require the use of + [XPATH] or [SAX]
    • +
  • This specification places no constraints on the order in which + software transforming RDF/XML into a representation of a graph, + constructs the representation of the graph.
    • +
  • Software transforming RDF/XML into a representation of a graph + MAY eliminate duplicate predicate arcs.
    • +
+ +

The syntax does not support non-well-formed XML documents, nor + documents that otherwise do not have an XML Information Set; for + example, that do not conform to + Namespaces in XML [XML-NAMES]. +

+ +

The Infoset requires support for + XML Base [XMLBASE]. + RDF/XML uses the information item property [base URI], discussed in + section 5.3 +

+ +

This specification requires an + XML Information Set [XML-INFOSET] + which supports at least the following information items and + properties for RDF/XML:

+ +
+
document information item
+
[document element], [children], [base URI]
+ +
element information item
+
[local name], [namespace name], [children], [attributes], [parent], [base URI]
+ +
attribute information item
+
[local name], [namespace name], [normalized value]
+ +
character information item
+
[character code]
+
+ +

There is no mapping of the following items to data model events:

+ + +

Other information items and properties have no mapping to + syntax data model events. +

+ +

Element information items with reserved XML Names + (See Name + in XML 1.0) + are not mapped to data model element events. These are all those + with property [prefix] beginning with xml (case + independent comparison) and all those with [prefix] property + having no value and which have [local name] beginning with + xml (case independent comparison). +

+ +

All information items contained inside XML elements matching the + parseTypeLiteralPropertyElt + production form + XML literals + and do not follow this mapping. See + parseTypeLiteralPropertyElt + for further information.

+ +

This section is intended to satisfy the requirements for + Conformance + in the [XML-INFOSET] specification. + It specifies the information items and properties that are needed + to implement this specification. +

+
+ + + + +
+

6.1 Events

+ +

There are nine types of event defined in the following subsections. + Most events are constructed from an Infoset information item (except + for IRI, + blank node, + plain literal and + typed literal). The effect + of an event constructor is to create a new event with a unique identity, + distinct from all other events. Events have accessor operations on them + and most have the string-value accessor that may be a static value + or computed.

+ + + + +
+

6.1.1 Root Event

+ +

Constructed from a + document information item + and takes the following accessors and values.

+ +
+
document-element
+
Set to the value of document information item property [document-element].
+
children
+
Set to the value of document information item property [children].
+
base-uri
+
Set to the value of document information item property [base URI].
+
language
+
Set to the empty string.
+
+
+ + + + +
+

6.1.2 Element Event

+ +

Constructed from an + element information item + and takes the following accessors and values: +

+ + +
+
local-name
+
Set to the value of element information item property [local name].
+ +
namespace-name
+
Set to the value of element information item property [namespace name].
+ +
children
+
Set to the value of element information item property [children].
+ +
parent
+
Set to the value of element information item property [parent].
+ +
base-uri
+
Set to the value of element information item property [base URI].
+ +
attributes
+

Made from the value of element information item + property [attributes] which is a set of attribute + information items.

+ +

If this set contains an attribute information item xml:lang ( + [namespace name] property with the value + "http://www.w3.org/XML/1998/namespace" and + [local name] property value "lang") + it is removed from the set of attribute information items and the + ·language· accessor is set to the + [normalized-value] property of the attribute information item.

+ +

All remaining reserved XML Names + (see Name + in XML 1.0) + are now removed from the set. These are, all + attribute information items in the set with property [prefix] + beginning with xml (case independent + comparison) and all attribute information items with [prefix] + property having no value and which have [local name] beginning with + xml (case independent comparison) are removed. + Note that the [base URI] accessor is computed by XML Base before any + xml:base attribute information item is deleted.

+ +

The remaining set of attribute information items are then used + to construct a new set of + Attribute Events + which is assigned as the value of this accessor.

+
+ +
URI
+
Set to the string value of the concatenation of the + value of the namespace-name accessor and the value of the + local-name accessor. +
+ +
URI-string-value
+
+

The value is the concatenation of the following in this order "<", + the escaped value of the + ·URI· + accessor and ">".

+ +

The escaping of the + ·URI· + accessor uses the N-Triples escapes for + IRIs [[N_TRIPLES]]. +

+ +
+ +
li-counter
+
Set to the integer value 1.
+ +
language
+
Set from the + ·attributes· + as described above. + If no value is given from the attributes, the value is set to the value of + the language accessor on the parent event (either a + Root Event or an + Element Event), which may be the empty string. +
+ +
subject
+
Has no initial value. Takes a value that is an + Identifier event. + This accessor is used on elements that deal with one node in the RDF graph, + this generally being the subject of a statement.
+ +
+
+ + + + + +
+

6.1.3 End Element Event

+ +

Has no accessors. Marks the end of the containing element in + the sequence.

+
+ + + + + +
+

6.1.4 Attribute Event

+ +

Constructed from an + attribute information item + and takes the following accessors and values:

+ +
+
local-name
+
Set to the value of attribute information item property [local name].
+ +
namespace-name
+
Set to the value of attribute information item property [namespace name].
+ +
string-value
+
Set to the value of the attribute information item + property [normalized value] as specified by [XML10] (if an attribute whose normalized + value is a zero-length string, then the string-value is also + a zero-length string).
+ +
URI
+

If ·namespace-name· is present, + set to a string value of the concatenation of the value of the + ·namespace-name· accessor + and the value of the + ·local-name· accessor. + Otherwise if ·local-name· is + ID, about, resource, + parseType or type, set to a string + value of the concatenation of the + ·RDF namespace IRI· + and the value of the ·local-name· accessor. Other non-namespaced + ·local-name· accessor values are + forbidden.

+ +

The support for a limited set of non-namespaced names is + REQUIRED and intended to allow RDF/XML documents specified in + [RDFMS] to remain valid; new documents + SHOULD NOT use these unqualified attributes and applications MAY + choose to warn when the unqualified form is seen in a document.

+ +

The construction of IRIs from XML attributes can generate the same + IRIs from different XML attributes. This can cause ambiguity in the + grammar when matching attribute events (such as when + rdf:about and about XML attributes are + both present). Documents that have this are illegal. +

+ +
+ +
URI-string-value
+
+

The value is the concatenation of the following in this order "<", + the escaped value of the + ·URI· + accessor and ">".

+ +

The escaping of the + ·URI· + accessor uses the N-Triples escapes for + IRIs [N-TRIPLES]. +

+
+ +
+
+ + + + + +
+

6.1.5 Text Event

+ +

Constructed from a sequence of one or more consecutive + character information items. + Has the single accessor:

+ +
+
string-value
+
Set to the value of the string made from concatenating the + [character + code] property of each of the character information + items. +
+
+
+ + + + + +
+

6.1.6 IRI Event

+ +

+ An event for a IRIs which has the following accessors:

+ +
+
identifier
+
Takes a string value used as an IRI.
+ +
string-value
+

The value is the concatenation of "<", the escaped + value of the ·identifier· accessor and ">"

+ +

The escaping of the ·identifier· accessor value + uses the N-Triples escapes for IRIs [N-TRIPLES].

+ +
+ +
+ +

These events are constructed by giving a value for the + ·identifier· accessor. +

+ +

For further information on identifiers in the RDF graph, see + section 5.2.

+
+ + + + + +
+

6.1.7 Blank Node Identifier Event

+ +

An event for a + blank node identifier + which has the following accessors:

+ +
+
identifier
+ +
Takes a string value.
+ +
string-value
+
The value is a function of the value of the + ·identifier· accessor. + The value begins with "_:" and the entire value MUST match the + N-Triples + BLANK_NODE_LABELD production. + The function MUST preserve distinct blank node identity as + discussed in in section 5.2 + Identifiers.
+ +
+ +

These events are constructed by giving a value for the + ·identifier· accessor. +

+ +

For further information on identifiers in the RDF graph, see + section 5.2.

+
+ + + + + +
+

6.1.8 Plain Literal Event

+ +
Note

RDF/XML plain literals are in RDF 1.1 treated as + syntactic sugar for a literal with datatype + xsd:string (in case no language tag is present) + or as a literal with datatype rdf:langString (in + case a language tag is present). The mapping to N-Triples as + defined in this subsection is not affected by this change.

+ +

An event for a plain + literal which can have the following accessors:

+ +
+
literal-value
+
Takes a string value.
+ +
literal-language
+
Takes a string value used as a language tag in an RDF plain literal.
+ +
string-value
+

The value is calculated from the other accessors as follows.

+ +

If ·literal-language· is the empty string + then the value is the concatenation of """ (1 double quote), + the escaped value of the + ·literal-value· accessor + and """ (1 double quote).

+ +

Otherwise the value is the concatenation of """ (1 double quote), + the escaped value of the + ·literal-value· accessor + ""@" (1 double quote and a '@'), + and the value of the + ·literal-language· accessor.

+ +

The escaping of the ·literal-value· accessor value uses the N-Triples + escapes for strings as described in [N-TRIPLES] + for escaping certain characters such as ".

+
+
+ +

These events are constructed by giving values for the + ·literal-value· and + ·literal-language· accessors.

+ +
Note

+ Interoperability Note (Informative): + Literals beginning with a Unicode combining character are + allowed however they may cause interoperability problems. + See [CHARMOD] for further information. +

+
+ + + + + +
+

6.1.9 Typed Literal Event

+ +

An event for a typed literal which can have the following accessors:

+ +
+
literal-value
+
Takes a string value.
+ +
literal-datatype
+
Takes a string value used as an IRI.
+ +
string-value
+

The value is the concatenation of the following in this order + """ (1 double quote), + the escaped value of the + ·literal-value· accessor, + """ (1 double quote), "^^<", + the escaped value of the + ·literal-datatype· accessor + and ">". +

+ +

The escaping of the ·literal-value· accessor value + uses the N-Triples + escapes for strings [N-TRIPLES] + for escaping certain characters such as ". + The escaping of the ·literal-datatype· accessor value + must use the N-Triples escapes for IRI [N-TRIPLES].

+ +
+
+ +

These events are constructed by giving values for the + ·literal-value· + and ·literal-datatype· accessors.

+ +
Note

+ Interoperability Note (Informative): + Literals beginning with a Unicode combining character are + allowed however they may cause interoperability problems. + See [CHARMOD] for further information. +

+ +
Note

+ Implementation Note (Informative): + In XML Schema (part 1) [XMLSCHEMA-1], + white + space normalization + occurs during validation according to the value of the whiteSpace + facet. The syntax mapping used in this document occurs after this, + so the whiteSpace facet formally has no further effect. +

+
+ +
+ + + + +
+

6.2 Information Set Mapping

+ +

To transform the Infoset into the sequence of events + in document order, each + information item is transformed as described above to generate a + tree of events with accessors and values. Each element event is + then replaced as described below to turn the tree of events + into a sequence in document order.

+ +
    +
  1. The original element event
    2. +
  2. The value of the + children + accessor recursively transformed, a possibly empty ordered list of events.
    3. +
  3. An end element event
    4. +
+
+ + + + + +
+

6.3 Grammar Notation

+ +

The following notation is used to describe matching the sequence + of data model events as given in Section 6 + and the actions to perform for the matches. + The RDF/XML grammar is defined in terms of mapping from these matched + data model events to triples, using notation of the form:

+ +
+

+ number event-type event-content + +

+ +
+ action... +

+ + N-Triples + +

+
+
+ +

where the event-content is an expression matching + + event-types (as defined in Section 6.1), + using notation given in the following sections. + The number is used for reference purposes. + The grammar action may include generating + new triples to the graph, written in N-Triples [N-TRIPLES] + format. +

+ +

The following sections describe the general notation used and that + for event matching and actions.

+ + + + + +
+

6.3.1 Grammar General Notation

+ + + + + + + + + + + + + + + + + + + + +
NotationMeaning
event.accessorThe value of an event accessor.
rdf:XA URI as defined in section 5.1.
"ABC"A string of characters A, B, C in order.
+
+ + + + + +
+

6.3.2 Grammar Event Matching Notation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NotationMeaning
A == BEvent accessor A matches expression B.
A != BA is not equal to B.
A | B | ...The A, B, ... terms are alternatives.
A - BThe terms in A excluding all the terms in B.
anyURI.Any URI.
anyString.Any string.
list(item1, item2, ...); list()An ordered list of events. An empty list.
set(item1, item2, ...); set()An unordered set of events. An empty set.
*Zero or more of preceding term.
?Zero or one of preceding term.
+One or more of preceding term.
root(acc1 == value1,
+ +     acc2 == value2, ...)		Match a Root Event with accessors. +
start-element(acc1 == value1,
+     acc2 == value2, ...)
+ children
+ end-element()		Match a sequence of + Element Event with accessors, + a possibly empty list of events as element content and an + End Element Event. +
attribute(acc1 == value1,
+     acc2 == value2, ...)		Match an Attribute Event + with accessors.
text()Match a Text Event.
+
+ + + + + +
+

6.3.3 Grammar Action Notation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NotationMeaning
A := BAssigns A the value B.
concat(A, B, ..)A string created by concatenating the terms in order.
resolve(e, s)A string created by interpreting string s as a relative IRI to the + ·base-uri· accessor of 6.1.2 Element Event e + + as defined in Section 5.3 Resolving URIs. + The resulting string represents an + IRI.
generated-blank-node-id()A string value for a new distinct generated + blank node identifier + as defined in section 5.2 Identifiers. +
event.accessor := valueSets an event accessor to the given value.
uri(identifier := value)Create a new URI Reference Event.
bnodeid(identifier := value)Create a new Blank Node Identifier Event. See also section 5.2 Identifiers.
literal(literal-value := string,
+     literal-language := language, ...)		Create a new Plain Literal Event.
typed-literal(literal-value := string, ...)Create a new Typed Literal Event.
+
+
+
+ + + + +
+ + +

7. RDF/XML Grammar

+ + + + + +
+

7.1 Grammar summary

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
7.2.2 coreSyntaxTerms rdf:RDF | rdf:ID | rdf:about | rdf:parseType | rdf:resource | rdf:nodeID | rdf:datatype
7.2.3 syntaxTerms coreSyntaxTerms | rdf:Description | rdf:li
7.2.4 oldTerms rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID
7.2.5 nodeElementURIs anyURI - ( coreSyntaxTerms | rdf:li | oldTerms )
7.2.6 propertyElementURIs anyURI - ( coreSyntaxTerms | rdf:Description | oldTerms )
7.2.7 propertyAttributeURIs anyURI - ( coreSyntaxTerms | rdf:Description | rdf:li | oldTerms )
7.2.8 doc root(document-element == RDF, + children == list(RDF))
7.2.9 RDF start-element(URI == rdf:RDF, + attributes == set())
+ nodeElementList
+ + end-element()
7.2.10 nodeElementList ws* (nodeElement ws* )*
7.2.11 nodeElement start-element(URI == nodeElementURIs
+     attributes == set((idAttr | nodeIdAttr | aboutAttr )?, propertyAttr*))
+ + propertyEltList
+ end-element()
7.2.12 ws A + text event matching white + space defined by XML [XML10] definition White Space + + Rule [3] S + in section + Common Syntactic Constructs
7.2.13 propertyEltList ws* (propertyElt ws* ) *
7.2.14 propertyElt resourcePropertyElt | + literalPropertyElt | + parseTypeLiteralPropertyElt | + parseTypeResourcePropertyElt | + + parseTypeCollectionPropertyElt | + parseTypeOtherPropertyElt | + emptyPropertyElt
7.2.15 resourcePropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?))
+ ws* nodeElement ws*
+ end-element()
7.2.16 literalPropertyElt start-element(URI == propertyElementURIs ), + attributes == set(idAttr?, datatypeAttr?))
+ + text()
+ end-element()
7.2.17 parseTypeLiteralPropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?, parseLiteral))
+ literal
+ end-element()
7.2.18 parseTypeResourcePropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?, parseResource))
+ propertyEltList
+ end-element()
7.2.19 parseTypeCollectionPropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?, parseCollection))
+ nodeElementList
+ end-element()
7.2.20 parseTypeOtherPropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?, parseOther))
+ propertyEltList
+ end-element()
7.2.21 emptyPropertyElt start-element(URI == propertyElementURIs ), + + attributes == set(idAttr?, ( resourceAttr | nodeIdAttr | datatypeAttr )?, propertyAttr*))
+ end-element()
7.2.22 idAttr attribute(URI == rdf:ID, + string-value == rdf-id)
7.2.23 nodeIdAttr attribute(URI == rdf:nodeID, + string-value == rdf-id)
7.2.24 aboutAttr attribute(URI == rdf:about, + string-value == URI-reference)
7.2.25 propertyAttr attribute(URI == propertyAttributeURIs, + string-value == anyString)
7.2.26 resourceAttr attribute(URI == rdf:resource, + string-value == URI-reference)
7.2.27 datatypeAttr attribute(URI == rdf:datatype, + string-value == URI-reference)
7.2.28 parseLiteral attribute(URI == rdf:parseType, + string-value == "Literal")
7.2.29 parseResource attribute(URI == rdf:parseType, + string-value == "Resource")
7.2.30 parseCollection attribute(URI == rdf:parseType, + string-value == "Collection")
7.2.31 parseOther attribute(URI == rdf:parseType, + + string-value == anyString - ("Resource" | "Literal" | "Collection") )
7.2.32 URI-reference An IRI.
7.2.33 literal Any XML element content + that is allowed according to + [XML10] definition Content of Elements + Rule [43] + content. + in section + 3.1 Start-Tags, End-Tags, and Empty-Element Tags
7.2.34 rdf-id An attribute ·string-value· + matching any legal [XML-NAMES] token + NCName
+ +
+
+ + + + +
+

7.2 Grammar Productions

+ + + + +
+

7.2.1 Grammar start

+ +

If the RDF/XML is a standalone XML document + (identified by presentation as an + application/rdf+xml RDF MIME type object, + or by some other means) then the grammar may start with + production doc or + production nodeElement.

+ +

If the content is known to be RDF/XML by context, such as when + RDF/XML is embedded inside other XML content, then the grammar + can either start + at Element Event  + RDF + (only when an element is legal at that point in the XML) + or at production nodeElementList + (only when element content is legal, since this is a list of elements). + For such embedded RDF/XML, the + ·base-uri· + value on the outermost element must be initialized from the containing + XML since no + Root Event  will be available. + Note that if such embedding occurs, the grammar may be entered + several times but no state is expected to be preserved.

+
+ + + + +
+

7.2.2 Production coreSyntaxTerms

+ +

+ rdf:RDF | rdf:ID | rdf:about | rdf:parseType | rdf:resource | rdf:nodeID | rdf:datatype + +

+ +

A subset of the syntax terms from the RDF vocabulary in + section 5.1 + which are used in RDF/XML. +

+
+ + + + +
+

7.2.3 Production syntaxTerms

+ +

+ coreSyntaxTerms | rdf:Description | rdf:li + +

+ +

All the syntax terms from the RDF vocabulary in + section 5.1 + which are used in RDF/XML. +

+
+ + + + +
+

7.2.4 Production oldTerms

+ +

+ rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID + +

+ +

These are the names from the RDF vocabulary + that have been withdrawn from the language. See the resolutions of + Issue rdfms-aboutEach-on-object, + Issue rdfms-abouteachprefix and + Last Call Issue timbl-01 + for further information. +

+ +
Note

Error Test: + Indicated by + error001.rdf and + error002.rdf +

+
+ + + + +
+

7.2.5 Production nodeElementURIs

+ +

+ anyURI - ( coreSyntaxTerms | rdf:li | oldTerms ) + +

+ +

The IRIs that are allowed on node elements.

+
+ + + + +
+

7.2.6 Production propertyElementURIs

+ +

+ anyURI - ( coreSyntaxTerms | rdf:Description | oldTerms ) + +

+ +

The URIs that are allowed on property elements.

+
+ + + + +
+

7.2.7 Production propertyAttributeURIs

+ +

+ anyURI - ( coreSyntaxTerms | rdf:Description | rdf:li | oldTerms ) + +

+ +

The IRIs that are allowed on property attributes.

+
+ + + + +
+

7.2.8 Production doc

+ +

+ root(document-element == RDF,
+ +     children == list(RDF)) +

+
+ + + + +
+

7.2.9 Production RDF

+ +

+ start-element(URI == rdf:RDF,
+ +     attributes == set())
+ nodeElementList
+ end-element() +

+
+ + + + +
+

7.2.10 Production nodeElementList

+ +

+ ws* (nodeElement ws* )* + +

+
+ + + + +
+

7.2.11 Production nodeElement

+ +

+ start-element(URI == nodeElementURIs
+     attributes == set((idAttr | nodeIdAttr | aboutAttr )?, propertyAttr*))
+ + propertyEltList
+ end-element() +

+ +

For node element e, the processing of some of the attributes + has to be done before other work such as dealing with children events + or other attributes. These can be processed in any order:

+ + + +

If e.subject is empty, + then e.subject := bnodeid(identifier := generated-blank-node-id()).

+ + +

The following can then be performed in any order:

+ + +
+ + + + +
+

7.2.12 Production ws

+ +

+ A text event matching white space + defined by [XML10] definition White Space + Rule [3] S + in section + Common Syntactic Constructs +

+
+ + + + +
+

7.2.13 Production propertyEltList

+ +

+ ws* (propertyElt ws* ) * +

+
+ + + + +
+

7.2.14 Production propertyElt

+ +

+ resourcePropertyElt | + literalPropertyElt | + parseTypeLiteralPropertyElt | + parseTypeResourcePropertyElt | + parseTypeCollectionPropertyElt | + + parseTypeOtherPropertyElt | + emptyPropertyElt +

+ +

If element e has + e.URI = + rdf:li then apply the list expansion rules on element e.parent in + + section 7.4 + to give a new URI u and + e.URI := u. +

+ +

The action of this production must be done before the + actions of any sub-matches (resourcePropertyElt ... emptyPropertyElt). + Alternatively the result must be equivalent to as if it this action + was performed first, such as performing as the first + action of all of the sub-matches. +

+
+ + + + +
+

7.2.15 Production resourcePropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+     attributes == set(idAttr?))
+ + ws* nodeElement ws*
+ end-element() +

+ +

For element e, and the single contained nodeElement + n, first n must be processed using production + + nodeElement. + Then the following statement is added to the graph:

+ +

+    e.parent.subject.string-value e.URI-string-value n.subject.string-value . + +

+ +

If the rdf:ID attribute a is given, the above + statement is reified with + i := uri(identifier := resolve(e, concat("#", a.string-value))) + using the reification rules in + + section 7.3 + and e.subject := i

+
+ + + + +
+

7.2.16 Production literalPropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+ +     attributes == set(idAttr?, datatypeAttr?))
+ text()
+ end-element() +

+ +

Note that the empty literal case is defined in production + emptyPropertyElt.

+ +

For element e, and the text event t. + The Unicode string t.string-value SHOULD be + in Normal Form C [NFC]. + If the rdf:datatype attribute d is given + then o := typed-literal(literal-value := t.string-value, literal-datatype := d.string-value) + otherwise + + o := literal(literal-value := t.string-value, literal-language := e.language) + and the following statement is added to the graph:

+ +

+ e.parent.subject.string-value e.URI-string-value o.string-value . + +

+ +

If the rdf:ID attribute a is given, the above + statement is reified with + i := uri(identifier := resolve(e, concat("#", a.string-value))) + using the reification rules in + + section 7.3 + and e.subject := i.

+
+ + + + +
+

7.2.17 Production parseTypeLiteralPropertyElt

This section is non-normative.

+ +

+ + start-element(URI == propertyElementURIs ),
+     attributes == set(idAttr?, parseLiteral))
+ literal
+ + end-element() +

+ + +

For element e and the literal l + that is the rdf:parseType="Literal" content. + l is not transformed by the syntax data model mapping into events + (as noted in section 6 Syntax Data Model) + but remains an XML Infoset of XML Information items.

+ +

l is transformed into the lexical form of an + XML literal + in the RDF graph x (a Unicode string) + by the following algorithm. This does not mandate any implementation + method — any other method that gives the same result may be used.

+ +
    + + + +
  1. Use l to construct an XPath + sequence [XPATH-DATAMODEL-30].
    2. +
  2. Apply http://www.w3.org/TR/xpath-functions-30/#func-serialize [XPATH-FUNCTIONS-30] + to this sequence to give an xsd:string x.
    3. +
  3. The Unicode string x is used as the lexical form of l
    4. +
  4. This Unicode string x SHOULD be in NFC Normal Form C [NFC]
    5. +
+ +

Then o := typed-literal(literal-value := x, literal-datatype := http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral ) + and the following statement is added to the graph:

+ +

+ e.parent.subject.string-value e.URI-string-value o.string-value . + +

+ +
Note

Test: + Empty literal case indicated by + test009.rdf + and + test009.nt +

+ +

If the rdf:ID attribute a is given, the above + statement is reified with + + i := uri(identifier := resolve(e, concat("#", a.string-value))) + using the reification rules in + section 7.3 + and e.subject := i.

+
+ + + + +
+

7.2.18 Production parseTypeResourcePropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+     attributes == set(idAttr?, parseResource))
+ + propertyEltList
+ end-element() +

+ +

For element e with possibly empty element content c.

+ +

n := bnodeid(identifier := generated-blank-node-id()).

+ +

Add the following statement to the graph: +

+

+ e.parent.subject.string-value e.URI-string-value n.string-value . + +

+ +
Note

Test: + Indicated by + test004.rdf + and + test004.nt +

+ +

If the rdf:ID attribute a is given, the + statement above is reified with + + i := uri(identifier := resolve(e, concat("#", a.string-value))) + using the reification rules in + section 7.3 + and e.subject := i.

+ +

If the element content c is not empty, then use event + n to create a new sequence of events as follows:

+

+ start-element(URI := rdf:Description,
+ +     subject := n,
+     attributes := set())
+ c
+ end-element() +

+ +

Then + process the resulting sequence using production + + nodeElement.

+
+ + + + +
+

7.2.19 Production parseTypeCollectionPropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+ +     attributes == set(idAttr?, parseCollection))
+ nodeElementList
+ end-element() +

+ +

For element event e with possibly empty + + nodeElementList l. Set + s:=list().

+ +

For each element event f in l, + n := bnodeid(identifier := generated-blank-node-id()) and append n to + + s to give a sequence of events.

+ +

If s is not empty, n is the first event identifier in + s and the following statement is added to the graph:

+

+ + e.parent.subject.string-value e.URI-string-value n.string-value . +

+ +

otherwise the following statement is added to the graph:

+

+ e.parent.subject.string-value e.URI-string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#nil> . + +

+ +

If the rdf:ID attribute a is given, + either of the the above statements is reified with + i := uri(identifier := resolve(e, concat("#", a.string-value))) + using the reification rules in + + section 7.3. +

+ +

If s is empty, no further work is performed.

+ +

For each event n in s and the + corresponding element event f in l, the following + statement is added to the graph:

+ +

+ n.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#first> f.string-value . +

+ +

For each consecutive and overlapping pair of events + (n, o) in s, the following statement is + added to the graph:

+ +

+ n.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#rest> o.string-value . + +

+ +

If s is not empty, n is the last event identifier + in s, the following statement is added to the graph:

+

+ n.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#rest> <http://www.w3.org/1999/02/22-rdf-syntax-ns#nil> . + +

+
+ + + + +
+

7.2.20 Production parseTypeOtherPropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+     attributes == set(idAttr?, parseOther))
+ + propertyEltList
+ end-element() +

+ + +

All rdf:parseType attribute values other than the strings + "Resource", "Literal" or "Collection" are treated as if the value was + "Literal". This production matches and acts as if production + parseTypeLiteralPropertyElt + was matched. + No extra triples are generated for other rdf:parseType values. +

+
+ + + + +
+

7.2.21 Production emptyPropertyElt

+ +

+ start-element(URI == propertyElementURIs ),
+     attributes == set(idAttr?, ( resourceAttr | nodeIdAttr | datatypeAttr )?, propertyAttr*))
+ + end-element() +

+ + +
+ + + + +
+

7.2.22 Production idAttr

+ + + + +

+ attribute(URI == rdf:ID,
+ +     string-value == rdf-id) +

+ +

Constraint:: constraint-id + applies to the values of rdf:ID attributes

+
+ + + + +
+

7.2.23 Production nodeIdAttr

+ +

+ attribute(URI == rdf:nodeID,
+     string-value == rdf-id) + +

+
+ + + + +
+

7.2.24 Production aboutAttr

+ +

+ attribute(URI == rdf:about,
+     string-value == URI-reference) + +

+
+ + + + +
+

7.2.25 Production propertyAttr

+ +

+ attribute(URI == propertyAttributeURIs,
+     string-value == anyString) + +

+
+ + + + +
+

7.2.26 Production resourceAttr

+ +

+ attribute(URI == rdf:resource,
+     string-value == URI-reference) + +

+
+ + + + +
+

7.2.27 Production datatypeAttr

+ +

+ attribute(URI == rdf:datatype,
+     string-value == URI-reference) + +

+
+ + + + +
+

7.2.28 Production parseLiteral

+ +

+ attribute(URI == rdf:parseType,
+     string-value == "Literal") + +

+
+ + + + +
+

7.2.29 Production parseResource

+ +

+ attribute(URI == rdf:parseType,
+     string-value == "Resource") + +

+
+ + + + +
+

7.2.30 Production parseCollection

+ +

+ attribute(URI == rdf:parseType,
+     string-value == "Collection") + +

+
+ + + + +
+

7.2.31 Production parseOther

+ +

+ attribute(URI == rdf:parseType,
+     string-value == anyString - ("Resource" | "Literal" | "Collection") ) + +

+
+ + + + +
+

7.2.32 Production IRI

+ +

+ An IRI. +

+
+ + + + +
+

7.2.33 Production literal

+ +

+ + Any XML element content that is allowed according to + XML definition Content of Elements + Rule [43] + content. + in section + 3.1 Start-Tags, End-Tags, and Empty-Element Tags +

+ +

The string-value for the resulting event is discussed in + section 7.2.17.

+ +
+
+ + + + +
+

7.2.34 Production rdf-id

+ +

+ An attribute ·string-value· + matching any legal + [XML-NAMES] token + NCName + +

+
+ +
+ + + + +
+

7.3 Reification Rules

+ +

For the given IRI event r and + the statement with terms s, p and o + + corresponding to the N-Triples:

+

+ s p o . +

+ +

add the following statements to the graph:

+

+ r.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#subject> s .
+ + r.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#predicate> p .
+ r.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#object> o .
+ + r.string-value <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/1999/02/22-rdf-syntax-ns#Statement> .
+

+
+ + + + +
+

7.4 List Expansion Rules

+ +

For the given element e, create a new IRI u := + concat("http://www.w3.org/1999/02/22-rdf-syntax-ns#_", + + e.li-counter), + increment the + e.li-counter + property by 1 and return u.

+
+ +
+ + + + +
+ + +

8. Serializing an RDF Graph to RDF/XML

+ +

There are some RDF Graphs as defined in + [RDF11-CONCEPTS]that cannot be serialized in RDF/XML. These are those that:

+ +
+
Use property names that cannot be turned into XML namespace-qualified names.
+
An XML namespace-qualified name + (QName) + has restrictions on the legal characters such that not all property URIs + can be expressed as these names. + It is recommended that implementors of RDF serializers, in order to + break a URI into a namespace name and a local name, split it after + the last XML non-NCName + character, ensuring that the first character of the name is a + Letter or '_'. + If the URI ends in a + non-NCName + character then throw a "this graph cannot be serialized in RDF/XML" + exception or error. +
+ +
Use inappropriate reserved names as properties
+
For example, a property with the same URI as any of the + syntaxTerms production. +
+ +
Use the rdf:HTML datatype
+
This datatype as introduced in RDF 1.1 + [RDF11-CONCEPTS].
+ +
+ +
Note

Implementation Note (Informative): + When an RDF graph is serialized to RDF/XML and has an XML Schema + Datatype (XSD), it SHOULD be written in a form that does not require + whitespace processing. XSD support is NOT required by RDF or RDF/XML + so this is optional. +

+
+ + + + + +
+ + +

9. Using RDF/XML with SVG

This section is non-normative.

+ +

There is a standardized approach for associating RDF compatible + metadata with SVG — the metadata element which was explicitly + designed for this purpose as defined in + Section 21 Metadata + + of the + Scalable + Vector Graphics (SVG) 1.0 Specification + [SVG10] + and + Section 21 Metadata + of the + Scalable + Vector Graphics (SVG) 1.1 Specification + [SVG11]. + +

+ +

This document contains two example graphs in SVG with such + embedded RDF/XML inside the metadata element: + figure 1 + + and + figure 2. +

+
+ + + + +
+ + +

A. Acknowledgments

This section is non-normative.

+ +

Gavin Carothers provided the RDF 1.1 update for the Production + parseTypeLiteralPropertyElt. Ivan Herman provided valuable + comments and reworked Figs 1 and 2.

+ +

This specification is a product of extended deliberations by the + members of the RDFcore Working Group and the RDF and RDF Schema Working Group.

+ +

The following people provided valuable contributions to the document:

+ +
    +
  • Dan Brickley, W3C/ILRT
    • +
  • Jeremy Carroll, HP Labs, Bristol
    • +
  • Graham Klyne, Nine by Nine
    • +
  • Bijan Parsia, MIND Lab at University of Maryland at College Park
    • +
+ +

This document is a product of extended deliberations by the RDF + Core working group, whose members have included: Art Barstow (W3C) + Dave Beckett (ILRT), Dan Brickley (W3C/ILRT), Dan Connolly (W3C), + Jeremy Carroll (Hewlett Packard), Ron Daniel (Interwoven Inc), Bill + dehOra (InterX), Jos De Roo (AGFA), Jan Grant (ILRT), Graham Klyne + (Clearswift and Nine by Nine), Frank Manola (MITRE Corporation), + Brian McBride (Hewlett Packard), Eric Miller (W3C), Stephen + Petschulat (IBM), Patrick Stickler (Nokia), Aaron Swartz (HWG), Mike + Dean (BBN Technologies / Verizon), R. V. Guha (Alpiri Inc), Pat Hayes + (IHMC), Sergey Melnik (Stanford University), Martyn Horner (Profium + Ltd).

+ +

This specification also draws upon an earlier RDF Model and Syntax + document edited by Ora Lassilla and Ralph Swick, and RDF Schema + edited by Dan Brickley and R. V. Guha. RDF and RDF Schema Working + group members who contributed to this earlier work are: + Nick Arnett (Verity), Tim Berners-Lee (W3C), Tim Bray (Textuality), + Dan Brickley (ILRT / University of Bristol), Walter Chang (Adobe), + Sailesh Chutani (Oracle), Dan Connolly (W3C), Ron Daniel + (DATAFUSION), Charles Frankston (Microsoft), Patrick Gannon + (CommerceNet), RV Guha (Epinions, previously of Netscape + Communications), Tom Hill (Apple Computer), Arthur van Hoff + (Marimba), Renato Iannella (DSTC), Sandeep Jain (Oracle), Kevin + Jones, (InterMind), Emiko Kezuka (Digital Vision Laboratories), Joe + Lapp (webMethods Inc.), Ora Lassila (Nokia Research Center), Andrew + Layman (Microsoft), Ralph LeVan (OCLC), John McCarthy (Lawrence + Berkeley National Laboratory), Chris McConnell (Microsoft), Murray + Maloney (Grif), Michael Mealling (Network Solutions), Norbert Mikula + (DataChannel), Eric Miller (OCLC), Jim Miller (W3C, emeritus), Frank + Olken (Lawrence Berkeley National Laboratory), Jean Paoli + (Microsoft), Sri Raghavan (Digital/Compaq), Lisa Rein (webMethods + Inc.), Paul Resnick (University of Michigan), Bill Roberts + (KnowledgeCite), Tsuyoshi Sakata (Digital Vision Laboratories), Bob + Schloss (IBM), Leon Shklar (Pencom Web Works), David Singer (IBM), + Wei (William) Song (SISU), Neel Sundaresan (IBM), Ralph Swick (W3C), + Naohiko Uramoto (IBM), Charles Wicksteed (Reuters Ltd.), Misha Wolf + (Reuters Ltd.), Lauren Wood (SoftQuad). +

+
+ +
+ + +

B. Changes since 2004 Recommendation

This section is non-normative.

+

Changes for RDF 1.1 Recommendation

+
    +
  • No changes.
    • +
+

Changes for RDF 1.1 Proposed Edited Recommendation:

+
    +
  1. Conversion to ReSpec.
    2. +
  2. RDF 2004 errata handling: +
      +
    1. Replaced hard-coded reference to XML and Unicode versions + (background info)
      2. +
    2. Corrected the resolve action with the signature resolve(e, s) + (background info)
      3. +
    3. Added parent accessor to element events + (background info)
      4. +
    4. Allow datatyped empty literals + (background info)
      5. +
    5. Removed ID and datatype exclusion on literal property + (background info)
      6. +
    3. +
  3. Adapted and shortened introduction to reflect RDF 1.1
    4. +
  4. Updated references to RDF 1.1 documents
    5. +
  5. Replaced "(RDF) URI reference" with "IRI"
    6. +
  6. Removed Section on embedding RDF/XML into HTML
    7. +
  7. Removed "Specification" from the title to bring it in + line with other RDF 1.1 document titles
    8. +
  8. Updated references to other documents
    9. +
  9. Changed links in Sec. 2 examples from relative URI to + absolute URI; same for RELAX schema in Appendix.
    10. +
  10. Added note to section on plain-literal event
    11. +
  11. Updated link to QName definition in XML-NAMES
    12. +
  12. Added diff with 2004 Recommendation
    13. +
  13. Sections concerning rdf:XMLLiteral + (Sec. 2.8 + and Sec. 7.2.17) + marked as non-normative.
    14. +
  14. Adapted Production + parseTypeLiteralPropertyElt to cater for the non-normative + status of rdf:XMLLiteral.
    15. +
  15. Improved version of Figs. 1 and 2 (with same + content)
    16. +
  16. Removed old changes section
    17. +
  17. Informative notes at start of Sec. 5.1 removed, as these + have become irrelevant.
    18. +
  18. Added new datatype rdf:HTML to the list of things that + cannot be serialized in RDF/XML.
    19. +
  19. Replaced the link to 2004 N-Triples nodeID production to + the RDF 1.1 N-Triples BLANK_NODE_LABEL + production.
    20. +
+ +
+ + + + +
+ + +

C. Syntax Schemas

This section is non-normative.

+ +

This appendix contains XML schemas for validating RDF/XML forms. + These are example schemas for information only and are not part of + this specification.

+ + + + +
+

C.1 RELAX NG Compact Schema

This section is non-normative.

+ +

This is an example + schema in + RELAX NG Compact (for ease of reading) + for RDF/XML. Applications can also use the + RELAX NG XML version. + These formats are described in + RELAX NG [RELAXNG] + and RELAX NG Compact [RELAXNG-COMPACT].

+ +
Note

+ The RNGC schema has been updated to attempt to match the grammar but + this has not been checked or used to validate RDF/XML. +

+ + 
        #
+        # RELAX NG Compact Schema for RDF/XML Syntax
+        #
+        # This schema is for information only and NON-NORMATIVE
+        #
+        # It is based on one originally written by James Clark in
+        # http://lists.w3.org/Archives/Public/www-rdf-comments/2001JulSep/0248.html
+        # and updated with later changes.
+        #
+
+        namespace local = ""
+        namespace rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+        datatypes xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
+
+        start = doc
+
+        # I cannot seem to do this in RNGC so they are expanded in-line
+
+        # coreSyntaxTerms = rdf:RDF | rdf:ID | rdf:about | rdf:parseType | rdf:resource | rdf:nodeID | rdf:datatype
+        # syntaxTerms = coreSyntaxTerms | rdf:Description | rdf:li
+        # oldTerms    = rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID
+        # nodeElementURIs       = * - ( coreSyntaxTerms | rdf:li | oldTerms )
+        # propertyElementURIs   = * - ( coreSyntaxTerms | rdf:Description | oldTerms )
+        # propertyAttributeURIs = * - ( coreSyntaxTerms | rdf:Description | rdf:li | oldTerms )
+
+        # Also needed to allow rdf:li on all property element productions
+        # since we can't capture the rdf:li rewriting to rdf_<n> in relaxng
+
+        # Need to add these explicitly
+        xmllang = attribute xml:lang { text }
+        xmlbase = attribute xml:base { text }
+        # and to forbid every other xml:* attribute, element
+
+        doc = 
+          RDF | nodeElement
+
+        RDF =
+          element rdf:RDF { 
+             xmllang?, xmlbase?, nodeElementList
+        }
+
+        nodeElementList = 
+          nodeElement*
+
+          # Should be something like:
+          #  ws* , (  nodeElement , ws* )*
+          # but RELAXNG does this by default, ignoring whitespace separating tags.
+
+        nodeElement =
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype | rdf:li |
+                        rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID ) {
+              (idAttr | nodeIdAttr | aboutAttr )?, xmllang?, xmlbase?, propertyAttr*, propertyEltList
+          }
+
+          # It is not possible to say "and not things
+          # beginning with _ in the rdf: namespace" in RELAX NG.
+
+        ws = 
+          " "
+
+          # Not used in this RELAX NG schema; but should be any legal XML
+          # whitespace defined by http://www.w3.org/TR/2000/REC-xml-20001006#NT-S
+
+
+        propertyEltList = 
+          propertyElt*
+
+          # Should be something like:
+          #  ws* , ( propertyElt , ws* )*
+          # but RELAXNG does this by default, ignoring whitespace separating tags.
+
+        propertyElt = 
+          resourcePropertyElt | 
+          literalPropertyElt | 
+          parseTypeLiteralPropertyElt |
+          parseTypeResourcePropertyElt |
+          parseTypeCollectionPropertyElt |
+          parseTypeOtherPropertyElt |
+          emptyPropertyElt
+
+        resourcePropertyElt = 
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr?, xmllang?, xmlbase?, nodeElement
+          }
+
+        literalPropertyElt =
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr? , datatypeAttr?, xmllang?, xmlbase?, text 
+          }
+
+        parseTypeLiteralPropertyElt = 
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr?, parseLiteral, xmllang?, xmlbase?, literal 
+          }
+
+        parseTypeResourcePropertyElt = 
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr?, parseResource, xmllang?, xmlbase?, propertyEltList
+          }
+
+        parseTypeCollectionPropertyElt = 
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr?, xmllang?, xmlbase?, parseCollection, nodeElementList
+          }
+
+        parseTypeOtherPropertyElt = 
+          element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                        rdf:resource | rdf:nodeID | rdf:datatype |
+                        rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                        xml:* ) {
+              idAttr?, xmllang?, xmlbase?, parseOther, any
+          }
+
+        emptyPropertyElt =
+           element * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                         rdf:resource | rdf:nodeID | rdf:datatype |
+                         rdf:Description | rdf:aboutEach | rdf:aboutEachPrefix | rdf:bagID |
+                         xml:* ) {
+               idAttr?, (resourceAttr | nodeIdAttr | datatypeAttr )?, xmllang?, xmlbase?, propertyAttr*
+           }
+
+        idAttr = 
+          attribute rdf:ID { 
+              IDsymbol 
+          }
+
+        nodeIdAttr = 
+          attribute rdf:nodeID { 
+              IDsymbol 
+          }
+
+        aboutAttr = 
+          attribute rdf:about { 
+              URI-reference 
+          }
+
+        propertyAttr = 
+          attribute * - ( local:* | rdf:RDF | rdf:ID | rdf:about | rdf:parseType |
+                          rdf:resource | rdf:nodeID | rdf:datatype | rdf:li |
+                          rdf:Description | rdf:aboutEach |
+                  rdf:aboutEachPrefix | rdf:bagID |
+                          xml:* ) {
+              string
+          }
+
+        resourceAttr = 
+          attribute rdf:resource {
+              URI-reference 
+          }
+
+        datatypeAttr = 
+          attribute rdf:datatype {
+              URI-reference 
+          }
+
+        parseLiteral = 
+          attribute rdf:parseType {
+              "Literal" 
+          }
+
+        parseResource = 
+          attribute rdf:parseType {
+              "Resource"
+          }
+
+        parseCollection = 
+          attribute rdf:parseType {
+              "Collection"
+          }
+
+        parseOther = 
+          attribute rdf:parseType {
+              text
+          }
+
+        URI-reference = 
+          string
+
+        literal =
+          any
+
+        IDsymbol = 
+          xsd:NMTOKEN
+
+        any =
+          mixed { element * { attribute * { text }*, any }* }
+
+ +
+
+ + + +
+ +

D. References

D.1 Normative references

[JSON-LD]
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Editors. JSON-LD 1.0. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/json-ld/ +
[N-TRIPLES]
Gavin Carothers, Andy Seabourne. RDF 1.1 N-Triples. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-n-triples-20140225/. The latest edition is available at http://www.w3.org/TR/n-triples/ +
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-concepts/ +
[RDF11-MT]
Patrick J. Hayes, Peter F. Patel-Schneider. RDF 1.1 Semantics. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-mt-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-mt/ +
[RDF11-SCHEMA]
Dan Brickley, R. V. Guha. RDF Schema 1.1. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf-schema-20140225/. The latest published version is available at http://www.w3.org/TR/rdf-schema/. +
[RDFA-PRIMER]
Ivan Herman; Ben Adida; Manu Sporny; Mark Birbeck. RDFa 1.1 Primer - Second Edition. 22 August 2013. W3C Note. URL: http://www.w3.org/TR/rdfa-primer/ +
[RFC3023]
M. Murata; S. St.Laurent; D. Kohn. XML Media Types (RFC 3023). January 2001. RFC. URL: http://www.ietf.org/rfc/rfc3023.txt +
[TRIG]
Gavin Carothers, Andy Seaborne. TriG: RDF Dataset Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-trig-20140225/. The latest edition is available at http://www.w3.org/TR/trig/ +
[TURTLE]
Eric Prud'hommeaux, Gavin Carothers. RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-turtle-20140225/. The latest edition is available at http://www.w3.org/TR/turtle/ +
[XML-INFOSET]
John Cowan; Richard Tobin. XML Information Set (Second Edition). 4 February 2004. W3C Recommendation. URL: http://www.w3.org/TR/xml-infoset +
[XML-NAMES]
Tim Bray; Dave Hollander; Andrew Layman; Richard Tobin; Henry Thompson et al. Namespaces in XML 1.0 (Third Edition). 8 December 2009. W3C Recommendation. URL: http://www.w3.org/TR/xml-names +
[XML10]
Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/xml +
[XMLSCHEMA-2]
Paul V. Biron; Ashok Malhotra. XML Schema Part 2: Datatypes Second Edition. 28 October 2004. W3C Recommendation. URL: http://www.w3.org/TR/xmlschema-2/ +

D.2 Informative references

[CHARMOD]
Martin Dürst; François Yergeau; Richard Ishida; Misha Wolf; Tex Texin et al. Character Model for the World Wide Web 1.0: Fundamentals. 15 February 2005. W3C Recommendation. URL: http://www.w3.org/TR/charmod/ +
[IANA-MEDIA-TYPES]
MIME Media Types. The Internet Assigned Numbers Authority (IANA). The registration for application/rdf+xml is archived at http://www.w3.org/2001/sw/RDFCore/mediatype-registration. +
[NFC]
M. Davis, Ken Whistler. TR15, Unicode Normalization Forms.. 17 September 2010, URL: http://www.unicode.org/reports/tr15/ +
[RDFMS]
Ora Lassila; Ralph R. Swick. Resource Description Framework (RDF) Model and Syntax Specification. 22 February 1999. W3C Recommendation. URL: http://www.w3.org/TR/1999/REC-rdf-syntax-19990222. +
[RELAXNG]
James Clark and Murata Makoto, editors. RELAX NG Specification. OASIS Committee Specification, 3 December 2001. Latest version: http://www.oasis-open.org/committees/relax-ng/spec.html. +
[RELAXNG-COMPACT]
James Clark, editor. RELAX NG Compact Syntax. OASIS Committee Specification, 21 November 2002. URI: http://www.oasis-open.org/committees/relax-ng/compact-20021121.html. +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[SAX]
D. Megginson, et al. SAX: The Simple API for XML. May 1998. URL: http://www.megginson.com/downloads/SAX/ +
[STRIPEDRDF]
D. Brickley. RDF: Understanding the Striped RDF/XML Syntax. W3C, 2001. URI: http://www.w3.org/2001/10/stripes/. +
[SVG10]
Jon Ferraiolo. Scalable Vector Graphics (SVG) 1.0 Specification. 4 September 2001. W3C Recommendation. URL: http://www.w3.org/TR/SVG/ +
[SVG11]
Erik Dahlström; Patrick Dengler; Anthony Grasso; Chris Lilley; Cameron McCormack; Doug Schepers; Jonathan Watt; Jon Ferraiolo; Jun Fujisawa; Dean Jackson et al. Scalable Vector Graphics (SVG) 1.1 (Second Edition). 16 August 2011. W3C Recommendation. URL: http://www.w3.org/TR/SVG11/ +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[XMLBASE]
Jonathan Marsh; Richard Tobin. XML Base (Second Edition). 28 January 2009. W3C Recommendation. URL: http://www.w3.org/TR/xmlbase/ +
[XMLSCHEMA-1]
Henry Thompson; David Beech; Murray Maloney; Noah Mendelsohn et al. XML Schema Part 1: Structures Second Edition. 28 October 2004. W3C Recommendation. URL: http://www.w3.org/TR/xmlschema-1/ +
[XPATH]
James Clark; Steven DeRose. XML Path Language (XPath) Version 1.0. 16 November 1999. W3C Recommendation. URL: http://www.w3.org/TR/xpath +
[XPATH-DATAMODEL-30]
Norman Walsh; Anders Berglund; John Snelson. XQuery and XPath Data Model 3.0. 22 October 2013. W3C Proposed Recommendation. URL: http://www.w3.org/TR/xpath-datamodel-30/ +
[XPATH-FUNCTIONS-30]
Michael Kay. XPath and XQuery Functions and Operators 3.0. 22 October 2013. W3C Proposed Recommendation. URL: http://www.w3.org/TR/xpath-functions-30/ +
\ No newline at end of file diff --git a/docs/standards/references/rdf11-concepts.html b/docs/standards/references/rdf11-concepts.html new file mode 100644 index 0000000..78b5a5b --- /dev/null +++ b/docs/standards/references/rdf11-concepts.html @@ -0,0 +1,1655 @@ + + + + + RDF 1.1 Concepts and Abstract Syntax + + + + + + + + + +

Abstract

+ +

The Resource Description Framework (RDF) is a framework for + representing information in the Web. This document defines an abstract syntax + (a data model) which serves to link all RDF-based languages and + specifications. The abstract syntax has two key data structures: + RDF graphs are sets of subject-predicate-object triples, + where the elements may be IRIs, blank nodes, or datatyped literals. They + are used to express descriptions of resources. RDF datasets are used + to organize collections of RDF graphs, and comprise a default graph + and zero or more named graphs. RDF 1.1 Concepts and Abstract Syntax + also introduces key concepts and terminology, and discusses + datatyping and the handling of fragment identifiers in IRIs within + RDF graphs.

+

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

This document is part of the RDF 1.1 document suite. It is the central + RDF 1.1 specification and defines the core RDF concepts. A new concept in + RDF 1.1 is the notion of an RDF dataset to represent multiple + graphs. Test suites and implementation reports of a number of RDF 1.1 + specifications that build on this document are available through the + RDF 1.1 Test Cases + document [RDF11-TESTCASES]. + There have been no changes to this document since its publication as + Proposed Recommendation.

+ +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + +
+ + +

1. Introduction

This section is non-normative.

+ +

The Resource Description Framework (RDF) is a framework + for representing information in the Web.

+ +

This document defines an abstract syntax (a data model) + which serves to link all RDF-based languages and specifications, + including:

+ + + +
+

1.1 Graph-based Data Model

+ +

The core structure of the abstract syntax is a set of + triples, each consisting of a subject, + a predicate and an object. A set of such triples is called + an RDF graph. An RDF graph can be visualized as a node and + directed-arc diagram, in which each triple is represented as a + node-arc-node link.

+ +
+ An RDF graph with two nodes (Subject and Object) and a triple connecting them (Predicate) +
Fig. 1 An RDF graph with two nodes (Subject and Object) and a triple connecting them (Predicate)
+
+ +

There can be three kinds of nodes in an + RDF graph: IRIs, literals, + and blank nodes.

+
+ + +
+

1.2 Resources and Statements

+ +

Any IRI or literal denotes + something in the world (the "universe of discourse"). + These things are called + resources. Anything can be a resource, + including physical things, documents, abstract concepts, numbers + and strings; the term is synonymous with "entity" as it is used in + the RDF Semantics specification [RDF11-MT]. + The resource denoted by an IRI is called its referent, and the + resource denoted by a literal is called its + literal value. Literals have + datatypes that define the range of possible + values, such as strings, numbers, and dates. Special kind of literals, + language-tagged strings, denote + plain-text strings in a natural language.

+ +

Asserting an RDF triple says that some relationship, + indicated by the predicate, holds between the + resources denoted by + the subject and object. This statement corresponding + to an RDF triple is known as an RDF statement. + The predicate itself is an IRI and denotes a property, + that is, a resource that can be thought of as a binary relation. + (Relations that involve more than two entities can only be + indirectly + expressed in RDF [SWBP-N-ARYRELATIONS].)

+ +

Unlike IRIs and literals, + blank nodes do not identify specific + resources. Statements + involving blank nodes say that something with the given relationships + exists, without explicitly naming it.

+
+ + +
+

1.3 The Referent of an IRI

+ +

The resource denoted by an IRI + is also called its referent. For some IRIs with particular + meanings, such as those identifying XSD datatypes, the referent is + fixed by this specification. For all other IRIs, what exactly is + denoted by any given IRI is not defined by this specification. Other + specifications may fix IRI referents, or apply other constraints on + what may be the referent of any IRI.

+ +

Guidelines for determining the referent of an IRI are + provided in other documents, like + Architecture of the World Wide Web, Volume One [WEBARCH] + and Cool URIs for the Semantic Web [COOLURIS]. + A very brief, informal, and partial account follows:

+ +
    +
  • By design, IRIs have global scope. Thus, two different appearances of an IRI + denote the same resource. Violating this principle constitutes + an IRI collision [WEBARCH].
    • + +
  • By social convention, the + IRI owner + [WEBARCH] gets to say what the intended (or usual) + referent of an IRI is. Applications and users need not + abide by this intended denotation, but there may be a loss of + interoperability with other applications and users if they do + not do so.
    • + +
  • The IRI owner can establish the intended referent + by means of a specification or other document that explains + what is denoted. For example, the + Organization Ontology document [VOCAB-ORG] + specifies the intended referents of various IRIs that start with + http://www.w3.org/ns/org#.
    • + +
  • A good way of communicating the intended referent + is to set up the IRI so that it + dereferences [WEBARCH] + to such a document.
    • + +
  • Such a document can, in fact, be an RDF document + that describes the denoted resource by means of + RDF statements.
    • +
+ +

Perhaps the most important characteristic of IRIs + in web architecture is that they can be + dereferenced, + and hence serve as starting points for interactions with a remote server. + This specification is not concerned with such interactions. + It does not define an interaction model. It only treats IRIs as globally + unique identifiers in a graph data model that describes resources. + However, those interactions are critical to the concept of + Linked Data [LINKED-DATA], + which makes use of the RDF data model and serialization formats.

+
+ +
+

1.4 RDF Vocabularies and Namespace IRIs

+ +

An RDF vocabulary is a collection of IRIs + intended for use in RDF graphs. For example, + the IRIs documented in [RDF11-SCHEMA] are the RDF Schema vocabulary. + RDF Schema can itself be used to define and document additional + RDF vocabularies. Some such vocabularies are mentioned in the + Primer [RDF11-PRIMER].

+ +

The IRIs in an RDF vocabulary often begin with + a common substring known as a namespace IRI. + Some namespace IRIs are associated by convention with a short name + known as a namespace prefix. Some examples: + +

+ + + + + + + + + + + + + + + + + + + +
Some example namespace prefixes and IRIs
Namespace prefixNamespace IRIRDF vocabulary
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#The RDF built-in vocabulary [RDF11-SCHEMA]
rdfshttp://www.w3.org/2000/01/rdf-schema#The RDF Schema vocabulary [RDF11-SCHEMA]
xsdhttp://www.w3.org/2001/XMLSchema#The RDF-compatible XSD types
+ +

In some serialization formats it is common to abbreviate IRIs + that start with namespace IRIs by using a + namespace prefix in order to assist readability. For example, the IRI + http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral + would be abbreviated as rdf:XMLLiteral. + Note however that these abbreviations are not valid IRIs, + and must not be used in contexts where IRIs are expected. + Namespace IRIs and namespace prefixes are not a formal part of the + RDF data model. They are merely a syntactic convenience for + abbreviating IRIs.

+ +

The term “namespace” on its own does not have a + well-defined meaning in the context of RDF, but is sometimes informally + used to mean “namespace IRI” or “RDF vocabulary”.

+
+ + +
+

1.5 RDF and Change over Time

+ +

The RDF data model is atemporal: RDF graphs + are static snapshots of information.

+ +

However, RDF graphs can express information + about events and about temporal aspects of other entities, + given appropriate vocabulary terms.

+ +

Since RDF graphs are defined as mathematical + sets, adding or removing triples from an + RDF graph yields a different RDF graph.

+ +

We informally use the term RDF source to refer to a + persistent yet mutable source or container of + RDF graphs. An RDF source is a resource + that may be said to have a state that can change over time. + A snapshot of the state can be expressed as an RDF graph. + For example, any web document that has an RDF-bearing representation + may be considered an RDF source. Like all resources, RDF sources may + be named with IRIs and therefore described in + other RDF graphs.

+ +

Intuitively speaking, changes in the universe of discourse + can be reflected in the following ways:

+ +
    +
  • An IRI, once minted, should never + change its intended referent. (See + URI persistence + [WEBARCH].)
    • +
  • Literals, by design, are constants and + never change their value.
    • +
  • A relationship that holds between two resources + at one time may not hold at another time.
    • +
  • RDF sources may change their state over time. + That is, they may provide different RDF graphs + at different times.
    • +
  • Some RDF sources may, however, be immutable + snapshots of another RDF source, archiving its state at some + point in time.
    • +
+ +
+ + +
+

1.6 Working with Multiple RDF Graphs

+ +

As RDF graphs are sets of triples, they can be + combined easily, supporting the use of data from + multiple sources. Nevertheless, it is sometimes desirable to work + with multiple RDF graphs while keeping their contents separate. + RDF datasets support this requirement.

+ +

An RDF dataset is a collection of + RDF graphs. All but one of these graphs have + an associated IRI or blank node. They are called + named graphs, and the IRI or blank node + is called the graph name. + The remaining graph does not have an associated IRI, and is called + the default graph of the RDF dataset.

+ +

There are many possible uses for RDF datasets. + One such use is to hold snapshots of multiple + RDF sources.

+
+ + +
+

1.7 Equivalence, Entailment and Inconsistency

+ +

An RDF triple encodes a statement—a + simple logical expression, or claim about the world. + An RDF graph is the conjunction (logical AND) of + its triples. The precise details of this meaning of RDF triples and graphs are + the subject of the RDF Semantics specification [RDF11-MT], which yields the + following relationships between RDF graphs:

+ +
+
Entailment
+
An RDF graph A entails another RDF graph B + if every possible arrangement of the world + that makes A true also makes B true. When A + entails B, if the truth of A is presumed or demonstrated + then the truth of B is established.
+ +
Equivalence
+
Two RDF graphs A and B + are equivalent if they make the same claim about the world. + A is equivalent to B if and only if + A entails B and + B entails A.
+ +
Inconsistency
+
An RDF graph is inconsistent if it contains + an internal contradiction. There is no possible arrangement + of the world that would make the expression true.
+
+ +

An entailment regime [RDF11-MT] is a specification that + defines precise conditions that make these relationships hold. + RDF itself recognizes only some basic cases of entailment, equivalence + and inconsistency. Other specifications, such as + RDF Schema [RDF11-SCHEMA] + and OWL 2 + [OWL2-OVERVIEW], add more powerful entailment regimes, + as do some domain-specific vocabularies. +

+ +

This specification does not constrain how implementations + use the logical relationships defined by + entailment regimes. + Implementations may or may not detect + inconsistencies, and may make all, + some or no entailed information + available to users.

+
+ + +
+

1.8 RDF Documents and Syntaxes

+ +

An RDF document is a document that encodes an + RDF graph or RDF dataset in a concrete RDF syntax, + such as Turtle [TURTLE], RDFa [RDFA-PRIMER], JSON-LD [JSON-LD], or + TriG [TRIG]. RDF documents enable the exchange of RDF graphs and RDF + datasets between systems.

+ +

A concrete RDF syntax may offer + many different ways to encode the same RDF graph or + RDF dataset, for example through the use of + namespace prefixes, + relative IRIs, blank node identifiers, + and different ordering of statements. While these aspects can have great + effect on the convenience of working with the RDF document, + they are not significant for its meaning.

+
+ + +
+ + +
+ +

2. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

+ The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, + and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. +

+ +

This specification, RDF 1.1 Concepts and Abstract Syntax, + defines a data model and related terminology for use in + other specifications, such as + concrete RDF syntaxes, + API specifications, and query languages. + Implementations cannot directly conform to + RDF 1.1 Concepts and Abstract Syntax, + but can conform to such other specifications that normatively + reference terms defined here.

+
+ + +
+ + +

3. RDF Graphs

+ +

An RDF graph is a set of + RDF triples.

+ + +
+

3.1 Triples

+ +

An RDF triple consists of three components:

+ + + +

An RDF triple is conventionally written in the order subject, + predicate, object.

+ +

The set of nodes of an RDF graph + is the set of subjects and objects of triples in the graph. + It is possible for a predicate IRI to also occur as a node in + the same graph.

+ +

IRIs, literals and + blank nodes are collectively known as + RDF terms.

+ +

IRIs, literals + and blank nodes are distinct and distinguishable. + For example, http://example.org/ as a string literal + is neither equal to http://example.org/ as an IRI, + nor to a blank node with the blank node identifier + http://example.org/.

+
+ + +
+

3.2 IRIs

+ +

An IRI + (Internationalized Resource Identifier) within an RDF graph + is a Unicode string [UNICODE] that conforms to the syntax + defined in RFC 3987 [RFC3987].

+ +

IRIs in the RDF abstract syntax MUST be absolute, and MAY + contain a fragment identifier.

+ +

IRI equality: + Two IRIs are equal if and only if they are equivalent + under Simple String Comparison according to + section 5.1 + of [RFC3987]. Further normalization MUST NOT be performed when + comparing IRIs for equality.

+ +
Note
+

URIs and IRIs: + IRIs are a generalization of + URIs + [RFC3986] that permits a wider range of Unicode characters. + Every absolute URI and URL is an IRI, but not every IRI is an URI. + When IRIs are used in operations that are only + defined for URIs, they must first be converted according to + the mapping defined in + section 3.1 + of [RFC3987]. A notable example is retrieval over the HTTP + protocol. The mapping involves UTF-8 encoding of non-ASCII + characters, %-encoding of octets not allowed in URIs, and + Punycode-encoding of domain names.

+ +

Relative IRIs: + Some concrete RDF syntaxes permit + relative IRIs as a convenient shorthand + that allows authoring of documents independently from their final + publishing location. Relative IRIs must be + resolved + against a base IRI to make them absolute. + Therefore, the RDF graph serialized in such syntaxes is well-defined only + if a base IRI + can be established [RFC3986].

+ +

IRI normalization: + Interoperability problems can be avoided by minting + only IRIs that are normalized according to + Section 5 + of [RFC3987]. Non-normalized forms that are best avoided + include:

+ +
    +
  • Uppercase characters in scheme names and domain names
    • +
  • Percent-encoding of characters where it is not + required by IRI syntax
    • +
  • Explicitly stated HTTP default port + (http://example.com:80/); + http://example.com/ is preferable
    • +
  • Completely empty path in HTTP IRIs + (http://example.com); + http://example.com/ is preferable
    • +
  • “/./” or “/../” in the path + component of an IRI
    • +
  • Lowercase hexadecimal letters within percent-encoding + triplets (“%3F” is preferable over + “%3f”)
    • +
  • Punycode-encoding of Internationalized Domain Names + in IRIs
    • +
  • IRIs that are not in Unicode Normalization + Form C [NFC]
    • +
+
+
+ + +
+

3.3 Literals

+ +

Literals are used for values such as strings, numbers, and dates.

+ +

A literal in an RDF graph consists of two or three + elements:

+ +
    +
  • a lexical form, being a Unicode [UNICODE] string, + which SHOULD be in Normal Form C [NFC],
    • +
  • a datatype IRI, being an IRI + identifying a datatype that determines how the lexical form maps + to a literal value, and
    • +
  • if and only if the datatype IRI is + http://www.w3.org/1999/02/22-rdf-syntax-ns#langString, a + non-empty language tag as defined by [BCP47]. The + language tag MUST be well-formed according to + section 2.2.9 + of [BCP47].
    • +
+ +

A literal is a language-tagged string if the third element + is present. Lexical representations of language tags MAY be converted + to lower case. The value space of language tags is always in lower + case.

+ +

Please note that concrete syntaxes MAY support + simple literals consisting of only a + lexical form without any datatype IRI or language tag. + Simple literals are syntactic sugar for abstract syntax + literals + with the datatype IRI + http://www.w3.org/2001/XMLSchema#string. Similarly, most + concrete syntaxes represent + language-tagged strings without + the datatype IRI because it always equals + http://www.w3.org/1999/02/22-rdf-syntax-ns#langString.

+ +

The literal value associated with a literal is:

+ +
    +
  1. If the literal is a language-tagged string, + then the literal value is a pair consisting of its lexical form + and its language tag, in that order.
    2. + +
  2. If the literal's datatype IRI is in the set of + recognized datatype IRIs, let d be the + referent of the datatype IRI. +
      +
    1. If the literal's lexical form is in the lexical space + of d, then the literal value is the result of applying + the lexical-to-value mapping of d to the + lexical form.
      2. +
    2. Otherwise, the literal is ill-typed and no literal value can be + associated with the literal. Such a case produces a semantic + inconsistency but is not syntactically ill-formed. + Implementations MUST accept ill-typed literals and produce RDF + graphs from them. Implementations MAY produce warnings when + encountering ill-typed literals.
      3. +
    +
    3. +
  3. If the literal's datatype IRI is not in the set of + recognized datatype IRIs, then the literal value is + not defined by this specification.
    4. +
+ +

Literal term equality: Two literals are term-equal (the same + RDF literal) if and only if the two lexical forms, + the two datatype IRIs, and the two + language tags (if any) compare equal, + character by character. Thus, two literals can have the same value + without being the same RDF term. For example:

+ + 
      "1"^^xs:integer
+      "01"^^xs:integer
+
+ +

denote the same value, but are not the + same literal RDF terms and are not + term-equal because their + lexical form differs.

+
+ + +
+

3.4 Blank Nodes

+ +

Blank nodes are disjoint from + IRIs and literals. Otherwise, + the set of possible blank nodes is arbitrary. RDF makes no reference to + any internal structure of blank nodes.

+ +
Note

+ Blank node identifiers + are local identifiers that are used in some + concrete RDF syntaxes + or RDF store implementations. + They are always locally scoped to the file or RDF store, + and are not persistent or portable identifiers + for blank nodes. Blank node identifiers are not + part of the RDF abstract syntax, but are entirely dependent + on the concrete syntax or implementation. The syntactic restrictions + on blank node identifiers, if any, therefore also depend on + the concrete RDF syntax or implementation. Implementations that handle blank node + identifiers in concrete syntaxes need to be careful not to create the + same blank node from multiple occurrences of the same blank node identifier + except in situations where this is supported by the syntax.

+
+ + +
+

3.5 Replacing Blank Nodes with IRIs

+ +

Blank nodes do not have identifiers in the RDF abstract syntax. The + blank node identifiers introduced + by some concrete syntaxes have only + local scope and are purely an artifact of the serialization.

+ +

In situations where stronger identification is needed, systems MAY + systematically replace some or all of the blank nodes in an RDF graph + with IRIs. Systems wishing to do this SHOULD + mint a new, globally + unique IRI (a Skolem IRI) for each blank node so replaced.

+ +

This transformation does not appreciably change the meaning of an + RDF graph, provided that the Skolem IRIs do not occur anywhere else. + It does however permit the possibility of other graphs + subsequently using the Skolem IRIs, which is not possible + for blank nodes.

+ +

Systems may wish to mint Skolem IRIs in such a way that they can + recognize the IRIs as having been introduced solely to replace blank + nodes. This allows a system to map IRIs back to blank nodes + if needed.

+ +

Systems that want Skolem IRIs to be recognizable outside of the system + boundaries SHOULD use a well-known IRI [RFC5785] with the registered + name genid. This is an IRI that uses the HTTP or HTTPS scheme, + or another scheme that has been specified to use well-known IRIs; and whose + path component starts with /.well-known/genid/. + +

For example, the authority responsible for the domain + example.com could mint the following recognizable Skolem IRI:

+ + 
http://example.com/.well-known/genid/d26a2d0e98334696f4ad70a677abc1f6
+ +
Note

RFC 5785 [RFC5785] only specifies well-known URIs, + not IRIs. For the purpose of this document, a well-known IRI is any + IRI that results in a well-known URI after IRI-to-URI mapping [RFC3987].

+
+ + +
+

3.6 Graph Comparison

+ +

Two + RDF graphs G and G' are + isomorphic (that is, they have an identical + form) if there is a bijection M between the sets of nodes of the two + graphs, such that:

+ +
    +
  1. M maps blank nodes to blank nodes.
    2. +
  2. M(lit)=lit for all RDF literals lit which + are nodes of G.
    3. + +
  3. M(iri)=iri for all IRIs iri + which are nodes of G.
    4. + +
  4. The triple ( s, p, o ) is in G if and + only if the triple ( M(s), p, M(o) ) is in + G'
    5. +
+ +

See also: IRI equality, literal term equality.

+ +

With this definition, M shows how each blank node + in G can be replaced with + a new blank node to give G'. Graph isomorphism + is needed to support the RDF Test Cases [RDF11-TESTCASES] specification.

+
+ +
+ + +
+ + +

4. RDF Datasets

+ +

An RDF dataset is a collection of + RDF graphs, and comprises:

+ +
    +
  • Exactly one default graph, being an RDF graph. + The default graph does not have a name and MAY be empty.
    • +
  • Zero or more named graphs. + Each named graph is a pair consisting of an IRI or a blank node + (the graph name), and an RDF graph. + Graph names are unique within an RDF dataset.
    • +
+ +

Blank nodes can be shared between graphs + in an RDF dataset.

+ +
Note
+

Despite the use of the word “name” in “named graph”, the + graph name is not required to denote the graph. It is + merely syntactically paired with the graph. RDF does not place any + formal restrictions on what resource the graph name may denote, + nor on the relationship between that resource and the graph. + A discussion of different RDF dataset semantics can be found in + [RDF11-DATASETS].

+ +

Some RDF dataset implementations do not + track empty named graphs. Applications + can avoid interoperability issues by not ascribing importance to + the presence or absence of empty named graphs.

+ +

SPARQL 1.1 [SPARQL11-OVERVIEW] also defines the concept of an RDF + Dataset. The definition of an RDF Dataset in SPARQL 1.1 and this + specification differ slightly in that this specification allows RDF + Graphs to be identified using either an IRI or a blank node. SPARQL 1.1 + Query Language only allows RDF Graphs to be identified using an IRI. + Existing SPARQL implementations might not allow blank nodes to be used + to identify RDF Graphs for some time, so their use can cause + interoperability problems. + Skolemizing blank nodes used as + graph names can be used to overcome these interoperability problems.

+
+ +
+

4.1 RDF Dataset Comparison

+ +

Two RDF datasets + (the RDF dataset D1 with default graph DG1 and any named + graph NG1 and the RDF dataset D2 with default graph + DG2 and any named graph NG2) + are dataset-isomorphic if and only if + there is a bijection M between the nodes, triples and graphs in + D1 and those in D2 such that:

+ +
    +
  1. M maps blank nodes to blank nodes;
    2. +
  2. M is the identity map on literals and URIs;
    3. +
  3. For every triple <s p o>, M(<s, p, o>)= + <M(s), M(p), M(o)>;
    4. +
  4. For every graph G={t1, ..., tn}, + M(G)={M(t1), ..., M(tn)};
    5. +
  5. DG2 = M(DG1); and
    6. +
  6. <n, G> is in NG1 if and only if + <M(n), M(G)> is in NG2. +
+ +
+ +
+

4.2 Content Negotiation of RDF Datasets

This section is non-normative.

+ +

Web resources may have multiple representations that are made available via + content negotiation + [WEBARCH]. A representation may be returned in an RDF serialization + format that supports the expression of both RDF datasets and + RDF graphs. If an RDF dataset + is returned and the consumer is expecting an RDF graph, + the consumer is expected to use the RDF dataset's default graph.

+ +
+ +
+ + +
+ + +

5. Datatypes

+ +

Datatypes are used with RDF literals + to represent values such as strings, numbers and dates. + The datatype abstraction used in RDF is compatible with XML Schema + [XMLSCHEMA11-2]. Any datatype definition that conforms + to this abstraction MAY be used in RDF, even if not defined + in terms of XML Schema. RDF re-uses many of the XML Schema + built-in datatypes, and defines two additional non-normative datatypes, + rdf:HTML and rdf:XMLLiteral. + The list of datatypes supported by an implementation is determined + by its recognized datatype IRIs.

+ +

A datatype consists of a lexical space, + a value space and a lexical-to-value mapping, and + is denoted by one or more IRIs.

+ +

The lexical space of a datatype is a set of Unicode [UNICODE] strings.

+ +

The lexical-to-value mapping of a datatype is a set of + pairs whose first element belongs to the lexical space, + and the second element belongs to the value space + of the datatype. Each member of the lexical space is paired with exactly + one value, and is a lexical representation + of that value. The mapping can be seen as a function + from the lexical space to the value space.

+ +
Note

Language-tagged + strings have the datatype IRI + http://www.w3.org/1999/02/22-rdf-syntax-ns#langString. + No datatype is formally defined for this IRI because the definition + of datatypes does not accommodate + language tags in the lexical space. + The value space associated with this datatype IRI is the set + of all pairs of strings and language tags.

+ +

For example, the XML Schema datatype xsd:boolean, + where each member of the value space has two lexical + representations, is defined as follows:

+ +
+
Lexical space:
+
{“true”, “false”, “1”, “0”}
+
Value space:
+
{true, false}
+
Lexical-to-value mapping
+
{ + <“true”, true>, + <“false”, false>, + <“1”, true>, + <“0”, false>, + }
+
+ +

The literals that can be defined using this + datatype are:

+ + + + + + + + + + + + + + + + + + + + + + + +
This table lists the literals of type xsd:boolean.
LiteralValue
<“true”, xsd:boolean>true
<“false”, xsd:boolean>false
<“1”, xsd:boolean>true
<“0”, xsd:boolean>false
+ + +
+

5.1 The XML Schema Built-in Datatypes

+ +

IRIs of the form + http://www.w3.org/2001/XMLSchema#xxx, + where xxx + is the name of a datatype, denote the built-in datatypes defined in + XML Schema 1.1 Part 2: + Datatypes [XMLSCHEMA11-2]. The XML Schema built-in types + listed in the following table are the + RDF-compatible XSD types. Their use is RECOMMENDED.

+ +

Readers might note that the xsd:hexBinary and xsd:base64Binary + datatypes are the only safe datatypes for transferring binary + information.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
A list of the RDF-compatible XSD types, with short descriptions"
DatatypeValue space (informative)
Core typesxsd:stringCharacter strings (but not all Unicode character strings)
xsd:booleantrue, false
xsd:decimalArbitrary-precision decimal numbers
xsd:integerArbitrary-size integer numbers
IEEE floating-point
numbers		xsd:double64-bit floating point numbers incl. ±Inf, ±0, NaN
xsd:float32-bit floating point numbers incl. ±Inf, ±0, NaN
Time and datexsd:dateDates (yyyy-mm-dd) with or without timezone
xsd:timeTimes (hh:mm:ss.sss…) with or without timezone
xsd:dateTimeDate and time with or without timezone
xsd:dateTimeStampDate and time with required timezone
Recurring and
partial dates		xsd:gYearGregorian calendar year
xsd:gMonthGregorian calendar month
xsd:gDayGregorian calendar day of the month
xsd:gYearMonthGregorian calendar year and month
xsd:gMonthDayGregorian calendar month and day
xsd:durationDuration of time
xsd:yearMonthDurationDuration of time (months and years only)
xsd:dayTimeDurationDuration of time (days, hours, minutes, seconds only)
Limited-range
integer numbers		xsd:byte-128…+127 (8 bit)
xsd:short-32768…+32767 (16 bit)
xsd:int-2147483648…+2147483647 (32 bit)
xsd:long-9223372036854775808…+9223372036854775807 (64 bit)
xsd:unsignedByte0…255 (8 bit)
xsd:unsignedShort0…65535 (16 bit)
xsd:unsignedInt0…4294967295 (32 bit)
xsd:unsignedLong0…18446744073709551615 (64 bit)
xsd:positiveIntegerInteger numbers >0
xsd:nonNegativeIntegerInteger numbers ≥0
xsd:negativeIntegerInteger numbers <0
xsd:nonPositiveIntegerInteger numbers ≤0
Encoded binary dataxsd:hexBinaryHex-encoded binary data
xsd:base64BinaryBase64-encoded binary data
Miscellaneous
XSD types		xsd:anyURIAbsolute or relative URIs and IRIs
xsd:languageLanguage tags per [BCP47]
xsd:normalizedStringWhitespace-normalized strings
xsd:tokenTokenized strings
xsd:NMTOKENXML NMTOKENs
xsd:NameXML Names
xsd:NCNameXML NCNames
+ +

The other built-in XML Schema datatypes are unsuitable + for various reasons and SHOULD NOT be used:

+ + + +
+ + +
+

5.2 The rdf:HTML Datatype

This section is non-normative.

+ +

RDF provides for HTML content as a possible literal value. + This allows markup in literal values. Such content is indicated + in an RDF graph using a literal whose datatype + is set to rdf:HTML. This datatype is defined + as non-normative because it depends on [DOM4], a specification that + has not yet reached W3C Recommendation status.

+ +

The rdf:HTML datatype is defined as follows:

+ +
+
The IRI denoting this datatype
+
is http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML.
+ +
The lexical space
+
is the set of Unicode [UNICODE] strings.
+ +
The value space
+
is a set of DOM + DocumentFragment + nodes [DOM4]. Two + DocumentFragment + nodes A and B are considered equal if and only if + the DOM method + A.isEqualNode(B) + [DOM4] returns true.
+ +
The lexical-to-value mapping
+
+

Each member of the lexical space is associated with the result + of applying the following algorithm:

+ +
+
+ +
Note

+ Any language annotation (lang="…") or + XML namespaces (xmlns) desired in the HTML content + must be included explicitly in the HTML literal. Relative URLs + in attributes such as href do not have a well-defined + base URL and are best avoided. + RDF applications may use additional equivalence relations, + such as that which relates an xsd:string with an + rdf:HTML literal corresponding to a single text node + of the same string.

+
+ +
+

5.3 The rdf:XMLLiteral Datatype

This section is non-normative.

+ +

RDF provides for XML content as a possible literal value. + Such content is indicated in an RDF graph using a literal + whose datatype is set to rdf:XMLLiteral. + This datatype is defined as non-normative because it depends on [DOM4], + a specification that has not yet reached W3C Recommendation status.

+ +

The rdf:XMLLiteral datatype is defined as follows:

+ +
+
The IRI denoting this datatype
+
is http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral.
+ +
The lexical space
+
is the set of all strings which are well-balanced, self-contained + XML content + [XML10]; and for which embedding between an arbitrary + XML start tag and an end tag yields a document conforming to + XML Namespaces + [XML-NAMES].
+ +
The value space
+
is a set of DOM + DocumentFragment + nodes [DOM4]. Two + DocumentFragment + nodes A and B are considered equal if and only if the DOM method + A.isEqualNode(B) + returns true.
+ +
The lexical-to-value mapping
+
+

Each member of the lexical space is associated with the result of applying the following algorithm:

+ +
+ +
The canonical mapping
+
defines a + canonical lexical form [XMLSCHEMA11-2] + for each member of the value space. The rdf:XMLLiteral canonical mapping is the + exclusive XML canonicalization method + (with comments, with empty + InclusiveNamespaces PrefixList) + [XML-EXC-C14N].
+
+ +
Note

Any XML namespace declarations (xmlns), + language annotation (xml:lang) or base URI declarations + (xml:base) desired in the XML content must be included + explicitly in the XML literal. Note that some concrete RDF syntaxes + may define mechanisms for inheriting them from the context (e.g., + @parseType="literal" + in RDF/XML [RDF11-XML]).

+
+ +
+

5.4 Datatype IRIs

+ +

Datatypes are identified by IRIs. If + D is a set of IRIs which are used to refer to + datatypes, then the elements of D are called recognized + datatype IRIs. Recognized IRIs have fixed + referents. If any IRI of the form + http://www.w3.org/2001/XMLSchema#xxx is recognized, it + MUST refer to the RDF-compatible XSD type named xsd:xxx for + every XSD type listed in section 5.1. + Furthermore, the following IRIs are allocated for non-normative + datatypes: + +

    +
  • The IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral + refers to the datatype rdf:XMLLiteral
    • +
  • The IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#HTML + refers to the datatype rdf:HTML
    • +
+ +
Note

Semantic extensions of RDF might choose to + recognize other datatype IRIs + and require them to refer to a fixed datatype. See the RDF + Semantics specification [RDF11-MT] for more information on + semantic extensions.

+ +

RDF processors are not required to recognize datatype IRIs. + Any literal typed with an unrecognized IRI is treated just like + an unknown IRI, i.e. as referring to an unknown thing. Applications + MAY give a warning message if they are unable to determine the + referent of an IRI used in a typed literal, but they SHOULD NOT + reject such RDF as either a syntactic or semantic error.

+ +

Other specifications MAY impose additional constraints on + datatype IRIs, for example, require support + for certain datatypes.

+ +
Note

The Web Ontology Language + [OWL2-OVERVIEW] offers facilities for formally defining + custom + datatypes that can be used with RDF. Furthermore, a practice for + identifying + + user-defined simple XML Schema datatypes + is suggested in [SWBP-XSCH-DATATYPES]. RDF implementations + are not required to support either of these facilities.

+
+ +
+ + +
+ + +

6. Fragment Identifiers

This section is non-normative.

+ +

RDF uses IRIs, which may include + fragment identifiers, as resource identifiers. + The semantics of fragment identifiers is + defined in + RFC 3986 [RFC3986]: They identify a secondary resource + that is usually a part of, view of, defined in, or described in + the primary resource, and the precise semantics depend on the set + of representations that might result from a retrieval action + on the primary resource.

+ +

This section discusses the handling of fragment identifiers + in representations that encode RDF graphs.

+ +

In RDF-bearing representations of a primary resource + <foo>, + the secondary resource identified by a fragment bar + is the resource denoted by the + full IRI <foo#bar> in the RDF graph. + Since IRIs in RDF graphs can denote anything, this can be + something external to the representation, or even external + to the web.

+ +

In this way, the RDF-bearing representation acts as an intermediary + between the web-accessible primary resource, and some set of possibly + non-web or abstract entities that the RDF graph may describe.

+ +

In cases where other specifications constrain the semantics of + fragment identifiers in RDF-bearing representations, the encoded + RDF graph should use fragment identifiers in a way that is consistent + with these constraints. For example, in an HTML+RDFa document [HTML-RDFA], + the fragment chapter1 may identify a document section + via the semantics of HTML's @name or @id + attributes. The IRI <#chapter1> should + then be taken to denote that same section in any RDFa-encoded + triples within the same document. + Similarly, fragment identifiers should be used consistently in resources + with multiple representations that are made available via + content negotiation + [WEBARCH]. For example, if the fragment chapter1 identifies a + document section in an HTML representation of the primary resource, then the + IRI <#chapter1> should be taken to + denote that same section in all RDF-bearing representations of the + same primary resource.

+
+ +
+ + +

7. Generalized RDF Triples, Graphs, and Datasets

This section is non-normative.

+ +

It is sometimes convenient to loosen the requirements + on RDF triples. For example, the completeness + of the RDFS entailment rules is easier to show with a + generalization of RDF triples.

+ +

A generalized RDF + triple is a triple having a subject, a predicate, + and object, where each can be an IRI, a + blank node or a + literal. A + generalized RDF graph + is a set of generalized RDF triples. A + generalized RDF dataset + comprises a distinguished generalized RDF graph, and zero + or more pairs each associating an IRI, a blank node or a literal + to a generalized RDF graph.

+ + +

Generalized RDF triples, graphs, and datasets differ + from normative RDF triples, + graphs, and + datasets only + by allowing IRIs, + blank nodes and + literals to appear + in any position, i.e., as subject, predicate, object or graph names.

+ +
Note

Any users of + generalized RDF triples, graphs or datasets need to be + aware that these notions are non-standard extensions of + RDF and their use may cause interoperability problems. + There is no requirement on the part of any RDF tool to + accept, process, or produce anything beyond standard RDF + triples, graphs, and datasets.

+ +
+ +
+ + +

8. Acknowledgments

This section is non-normative.

+ +

The editors acknowledge valuable contributions from Thomas Baker, + Tim Berners-Lee, David Booth, Dan Brickley, Gavin Carothers, Jeremy Carroll, + Pierre-Antoine Champin, Dan Connolly, John Cowan, Martin J. Dürst, + Alex Hall, Steve Harris, Sandro Hawke, Pat Hayes, Ivan Herman, Peter F. Patel-Schneider, + Addison Phillips, Eric Prud'hommeaux, Nathan Rixham, Andy Seaborne, Leif Halvard Silli, + Guus Schreiber, Dominik Tomaszuk, and Antoine Zimmermann.

+ +

The membership of the RDF Working Group included Thomas Baker, + Scott Bauer, Dan Brickley, Gavin Carothers, Pierre-Antoine Champin, + Olivier Corby, Richard Cyganiak, Souripriya Das, Ian Davis, Lee Feigenbaum, + Fabien Gandon, Charles Greer, Alex Hall, Steve Harris, Sandro Hawke, + Pat Hayes, Ivan Herman, Nicholas Humfrey, Kingsley Idehen, Gregg Kellogg, + Markus Lanthaler, Arnaud Le Hors, Peter F. Patel-Schneider, + Eric Prud'hommeaux, Yves Raimond, Nathan Rixham, Guus Schreiber, + Andy Seaborne, Manu Sporny, Thomas Steiner, Ted Thibodeau, Mischa Tuffield, + William Waites, Jan Wielemaker, David Wood, Zhe Wu, and Antoine Zimmermann.

+
+ + +
+ + +

A. Changes between RDF 1.0 and RDF 1.1

This section is non-normative.

+ +

A detailed overview of the differences between RDF versions 1.0 + and 1.1 can be found in + What’s New in RDF 1.1 [RDF11-NEW].

+
+ + + + +
+ +

B. References

B.1 Normative references

[BCP47]
A. Phillips; M. Davis. Tags for Identifying Languages. September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47 +
[NFC]
M. Davis, Ken Whistler. TR15, Unicode Normalization Forms.. 17 September 2010, URL: http://www.unicode.org/reports/tr15/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[XMLSCHEMA11-2]
David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. 5 April 2012. W3C Recommendation. URL: http://www.w3.org/TR/xmlschema11-2/ +

B.2 Informative references

[COOLURIS]
Leo Sauermann; Richard Cyganiak. Cool URIs for the Semantic Web. 3 December 2008. W3C Note. URL: http://www.w3.org/TR/cooluris +
[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 4 February 2014. W3C Last Call Working Draft. URL: http://www.w3.org/TR/dom/ +
[HTML-RDFA]
Manu Sporny. HTML+RDFa 1.1. 22 August 2013. W3C Recommendation. URL: http://www.w3.org/TR/html-rdfa/ +
[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. HTML5. 4 February 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/ +
[JSON-LD]
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Editors. JSON-LD 1.0. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/json-ld/ +
[LINKED-DATA]
Tim Berners-Lee. Linked Data. Personal View, imperfect but published. URL: http://www.w3.org/DesignIssues/LinkedData.html +
[OWL2-OVERVIEW]
W3C OWL Working Group. OWL 2 Web Ontology Language Document Overview (Second Edition). 11 December 2012. W3C Recommendation. URL: http://www.w3.org/TR/owl2-overview/ +
[RDF11-DATASETS]
Antoine Zimmermann. RDF 1.1: On Semantics of RDF Datasets. W3C Working Group Note, 25 February 2014. The latest version is available at http://www.w3.org/TR/rdf11-datasets/. +
[RDF11-MT]
Patrick J. Hayes, Peter F. Patel-Schneider. RDF 1.1 Semantics. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-mt-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-mt/ +
[RDF11-NEW]
David Wood. What’s New in RDF 1.1. W3C Working Group Note, 25 February 2014. The latest version is available at http://www.w3.org/TR/rdf11-new/. +
[RDF11-PRIMER]
Guus Schreiber, Yves Raimond. RDF 1.1 Primer. W3C Working Group Note, 25 February 2014. The latest version is available at http://www.w3.org/TR/rdf11-primer/. +
[RDF11-SCHEMA]
Dan Brickley, R. V. Guha. RDF Schema 1.1. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf-schema-20140225/. The latest published version is available at http://www.w3.org/TR/rdf-schema/. +
[RDF11-TESTCASES]
Gregg Kellogg, Markus Lanthaler. RDF 1.1 Test Cases. W3C Working Group Note, 25 February 2014. The latest published version is available at http://www.w3.org/TR/rdf11-testcases/. +
[RDF11-XML]
Fabien Gandon, Guus Schreiber. RDF 1.1 XML Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf-syntax-grammar-20140225/. The latest published version is available at http://www.w3.org/TR/rdf-syntax-grammar/. +
[RDFA-PRIMER]
Ivan Herman; Ben Adida; Manu Sporny; Mark Birbeck. RDFa 1.1 Primer - Second Edition. 22 August 2013. W3C Note. URL: http://www.w3.org/TR/rdfa-primer/ +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[RFC5785]
Mark Nottingham; Eran Hammer-Lahav. Defining Well-Known Uniform Resource Identifiers (URIs) (RFC 5785). April 2010. RFC. URL: http://www.rfc-editor.org/rfc/rfc5785.txt +
[SPARQL11-OVERVIEW]
The W3C SPARQL Working Group. SPARQL 1.1 Overview. 21 March 2013. W3C Recommendation. URL: http://www.w3.org/TR/sparql11-overview/ +
[SWBP-N-ARYRELATIONS]
Natasha Noy; Alan Rector. Defining N-ary Relations on the Semantic Web. 12 April 2006. W3C Note. URL: http://www.w3.org/TR/swbp-n-aryRelations +
[SWBP-XSCH-DATATYPES]
Jeremy Carroll; Jeff Pan. XML Schema Datatypes in RDF and OWL. 14 March 2006. W3C Note. URL: http://www.w3.org/TR/swbp-xsch-datatypes +
[TRIG]
Gavin Carothers, Andy Seaborne. TriG: RDF Dataset Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-trig-20140225/. The latest edition is available at http://www.w3.org/TR/trig/ +
[TURTLE]
Eric Prud'hommeaux, Gavin Carothers. RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-turtle-20140225/. The latest edition is available at http://www.w3.org/TR/turtle/ +
[VOCAB-ORG]
Dave Reynolds. The Organization Ontology. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/vocab-org/ +
[WEBARCH]
Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. 15 December 2004. W3C Recommendation. URL: http://www.w3.org/TR/webarch/ +
[XML-EXC-C14N]
John Boyer; Donald Eastlake; Joseph Reagle. Exclusive XML Canonicalization Version 1.0. 18 July 2002. W3C Recommendation. URL: http://www.w3.org/TR/xml-exc-c14n +
[XML-NAMES]
Tim Bray; Dave Hollander; Andrew Layman; Richard Tobin; Henry Thompson et al. Namespaces in XML 1.0 (Third Edition). 8 December 2009. W3C Recommendation. URL: http://www.w3.org/TR/xml-names +
[XML10]
Tim Bray; Jean Paoli; Michael Sperberg-McQueen; Eve Maler; François Yergeau et al. Extensible Markup Language (XML) 1.0 (Fifth Edition). 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/xml +
diff --git a/docs/standards/references/rfc3667.txt b/docs/standards/references/rfc3667.txt new file mode 100644 index 0000000..65d660c --- /dev/null +++ b/docs/standards/references/rfc3667.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group S. Bradner +Request for Comments: 3667 Harvard University +BCP: 78 February 2004 +Updates: 2026 +Category: Best Current Practice + + + IETF Rights in Contributions + +Status of this Memo + + This document specifies an Internet Best Current Practices for the + Internet Community, and requests discussion and suggestions for + improvements. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2004). All Rights Reserved. + +Abstract + + The IETF policies about rights in Contributions to the IETF are + designed to ensure that such Contributions can be made available to + the IETF and Internet communities while permitting the authors to + retain as many rights as possible. This memo details the IETF + policies on rights in Contributions to the IETF. It also describes + the objectives that the policies are designed to meet. This memo + updates RFC 2026, and, with RFC 3668, replaces Section 10 of RFC + 2026. + +Table of Contents + + 1. Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Rights in IETF Contributions . . . . . . . . . . . . . . . . . 5 + 3.1. General Policy . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Confidentiality Obligations. . . . . . . . . . . . . . . 5 + 3.3. Granting of Rights and Permissions . . . . . . . . . . . 6 + 3.4. Representations and Warranties . . . . . . . . . . . . . 7 + 3.5. No Duty to Publish . . . . . . . . . . . . . . . . . . . 7 + 3.6. Trademarks . . . . . . . . . . . . . . . . . . . . . . . 7 + 4. Rights in RFC Editor Contributions . . . . . . . . . . . . . . 8 + 4.1. Requirements from Section 3. . . . . . . . . . . . . . . 8 + 4.2. Granting of Rights and Permissions . . . . . . . . . . . 8 + 5. Notices Required in IETF Documents . . . . . . . . . . . . . . 9 + 5.1. IPR Disclosure Acknowledgement . . . . . . . . . . . . . 10 + 5.2. Derivative Works Limitation. . . . . . . . . . . . . . . 10 + 5.3. Publication Limitation . . . . . . . . . . . . . . . . . 11 + + + +Bradner Best Current Practice [Page 1] + +RFC 3667 IETF Rights in Submissions February 2004 + + + 5.4. Copyright Notice . . . . . . . . . . . . . . . . . . . . 11 + 5.5. Disclaimer . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.6. Exceptions . . . . . . . . . . . . . . . . . . . . . . . 12 + 6. Notices and Rights Required in RFC Editor Contributions. . . . 13 + 7. Exposition of why these procedures are the way they are. . . . 13 + 7.1. Rights Granted in IETF Contributions . . . . . . . . . . 13 + 7.2. Rights to use Contributed Material . . . . . . . . . . . 14 + 7.3. Right to Produce Derivative Works. . . . . . . . . . . . 14 + 7.4. Rights to use Trademarks . . . . . . . . . . . . . . . . 16 + 7.5. Who Does This Apply To?. . . . . . . . . . . . . . . . . 16 + 8. Contributions Not Subject to Copyright . . . . . . . . . . . . 16 + 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 16 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 17 + 10.2. Informative References . . . . . . . . . . . . . . . . . 17 + 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 + 12. Editor's Address . . . . . . . . . . . . . . . . . . . . . . . 17 + 13. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 18 + +1. Definitions + + The following definitions are for terms used in the context of this + document. Other terms, including "IESG," "ISOC," "IAB" and "RFC + Editor," are defined in [RFC 2028]. + + a. "IETF": In the context of this document, the IETF includes all + individuals who participate in meetings, working groups, mailing + lists, functions and other activities which are organized or + initiated by ISOC, the IESG or the IAB under the general + designation of the Internet Engineering Task Force or IETF, but + solely to the extent of such participation. + + b. "IETF Standards Process": the activities undertaken by the IETF in + any of the settings described in 1(c) below. + + c. "IETF Contribution": any submission to the IETF intended by the + Contributor for publication as all or part of an Internet-Draft or + RFC (except for RFC Editor Contributions described below) and any + statement made within the context of an IETF activity. Such + statements include oral statements in IETF sessions, as well as + written and electronic communications made at any time or place, + which are addressed to: + + o the IETF plenary session, + o any IETF working group or portion thereof, + o the IESG, or any member thereof on behalf of the IESG, + o the IAB or any member thereof on behalf of the IAB, + + + + +Bradner Best Current Practice [Page 2] + +RFC 3667 IETF Rights in Submissions February 2004 + + + o any IETF mailing list, including the IETF list itself, any + working group or design team list, or any other list + functioning under IETF auspices, + o the RFC Editor or the Internet-Drafts function (except for RFC + Editor Contributions described below). + + Statements made outside of an IETF session, mailing list or other + function, that are clearly not intended to be input to an IETF + activity, group or function, are not IETF Contributions in the + context of this document. + + d. "Internet-Draft": temporary documents used in the IETF and RFC + Editor processes. Internet-Drafts are posted on the IETF web site + by the IETF Secretariat and have a nominal maximum lifetime in the + Secretariat's public directory of 6 months, after which they are + removed. Note that Internet-Drafts are archived many places on + the Internet, and not all of these places remove expired + Internet-Drafts. Internet-Drafts that are under active + consideration by the IESG are not removed from the Secretariat's + public directory until that consideration is complete. In + addition, the author of an Internet-Draft can request that the + lifetime in the Secretariat's public directory be extended before + the expiration. + + e. "RFC": the basic publication series for the IETF. RFCs are + published by the RFC Editor and once published are never modified. + (See [RFC 2026] Section 2.1) + + f. "RFC Editor Contribution": An Internet-Draft intended by the + Contributor to be submitted to the RFC Editor for publication as + an Informational or Experimental RFC but not intended to be part + of the IETF Standards Process. + + g. "IETF Internet-Drafts": Internet-Drafts other than RFC Editor + Contributions. Note that under Section 3.3(a) the grant of rights + in regards to IETF Internet-Drafts as specified in this document + is perpetual and irrevocable and thus survives the Secretariat's + removal of an Internet-Draft from the public directory, except as + limited by Section 3.3(a)(C). (See [RFC 2026] Sections 2.2 and 8) + + h. "IETF Documents": RFCs and Internet-Drafts except for Internet- + Drafts that are RFC Editor Contributions and the RFCs that are + published from them. + + i. "RFC Editor Documents": RFCs and Internet-Drafts that are RFC + Editor Contributions and the RFCs that may be published from them. + + j. "Contribution": IETF Contributions and RFC Editor Contributions. + + + +Bradner Best Current Practice [Page 3] + +RFC 3667 IETF Rights in Submissions February 2004 + + + k. "Contributor": an individual submitting a Contribution. + + l. "Reasonably and personally known": means something an individual + knows personally or, because of the job the individual holds, + would reasonably be expected to know. This wording is used to + indicate that an organization cannot purposely keep an individual + in the dark about patents or patent applications just to avoid the + disclosure requirement. But this requirement should not be + interpreted as requiring the IETF Contributor or participant (or + his or her represented organization, if any) to perform a patent + search to find applicable IPR. + +2. Introduction + + Under the laws of most countries and current international treaties + (for example the "Berne Convention for the Protection of Literary and + Artistic Work" [Berne]), authors obtain numerous rights in the works + they produce automatically upon producing them. These rights include + copyrights, moral rights and other rights. In many cases, if the + author produces a work within the scope of his or her employment, + most of those rights are usually assigned to the employer, either by + operation of law or, in many cases, under contract. (The Berne + Convention names some rights as "inalienable", which means that the + author retains them in all cases.) + + This document details the rights that the IETF requires in IETF + Contributions and rights the IETF, as publisher of Internet-Drafts, + requires in all such Drafts including RFC Editor Contributions. The + RFC Editor may also define additional rights required for RFC Editor + Contributions. + + In order for works to be used within the IETF Standards Process or to + be published as Internet-Drafts, certain limited rights in all + Contributions must be granted to the IETF and Internet Society + (ISOC). In addition, Contributors must make representations to IETF + and ISOC regarding their ability to grant these rights. These + necessary rights and representations have until now been laid out in + Section 10 of [RFC 2026]. In the years since [RFC 2026] was + published there have been a number of times when the exact intent of + Section 10 has been the subject of vigorous debate within the IETF + community. The aim of this document is to clarify various + ambiguities in Section 10 of [RFC 2026] that led to these debates and + to amplify the policy in order to clarify what the IETF is currently + doing. + + Section 1 gives definitions used in describing these policies. + Sections 3, 4, 5 and 6 of this document address the rights in + Contributions previously covered by Section 10 of [RFC 2026] and the + + + +Bradner Best Current Practice [Page 4] + +RFC 3667 IETF Rights in Submissions February 2004 + + + "Note Well" explanatory text presented at many IETF activities. + Sections 7 and 8 then explain the rationale for these provisions, + including some of the clarifications that have become understood + since the adoption of [RFC 2026]. The rules and procedures set out + in this document are not intended to substantially modify or alter + the IETF's current policy toward Contributions. + + A companion document [RFC 3668] deals with rights in technologies + developed or specified as part of the IETF Standards Process. This + document is not intended to address those issues. + + The rights addressed in this document fall into the following + categories: + + o rights to make use of contributed material + o copyrights in IETF documents + o rights to produce derivative works + o rights to use trademarks + + This document is not intended as legal advice. Readers are advised + to consult their own legal advisors if they would like a legal + interpretation of their rights or the rights of the IETF in any + Contributions they make. + +3. Rights in IETF Contributions + + The following are the rights the IETF requires in all IETF + Contributions: + +3.1. General Policy + + In all matters of copyright and document procedures, the intent is to + benefit the Internet community and the public at large, while + respecting the legitimate rights of others. + +3.2. Confidentiality Obligations + + No information or document that is subject to any requirement of + confidentiality or any restriction on its dissemination may be + submitted as a Contribution or otherwise considered in any part of + the IETF Standards Process, and there must be no assumption of any + confidentiality obligation with respect to any Contribution. Each + Contributor agrees that any statement in a Contribution, whether + generated automatically or otherwise, that states or implies that the + Contribution is confidential or subject to any privilege, can be + disregarded for all purposes, and will be of no force or effect. + + + + + +Bradner Best Current Practice [Page 5] + +RFC 3667 IETF Rights in Submissions February 2004 + + +3.3. Granting of Rights and Permissions + + By submission of a Contribution, each person actually submitting the + Contribution, and each named co-Contributor, is deemed to agree to + the following terms and conditions, and to grant the following + rights, on his or her own behalf and on behalf of the organization + the Contributor represents or is sponsored by (if any) when + submitting the Contribution. + + a. To the extent that a Contribution or any portion thereof is + protected by copyright and other rights of authorship, the + Contributor, and each named co-Contributor, and the organization + he or she represents or is sponsored by (if any) grant a + perpetual, irrevocable, non-exclusive, royalty-free, world-wide + right and license to the ISOC and the IETF under all intellectual + property rights in the Contribution: + + (A) to copy, publish, display and distribute the Contribution as + part of the IETF Standards Process or in an Internet-Draft, + + (B) to prepare or allow the preparation of translations of the + Contribution into languages other than English, + + (C) unless explicitly disallowed in the notices contained in a + Contribution [as per Section 5.2 below], to prepare + derivative works (other than translations) that are based on + or incorporate all or part of the Contribution, or comment + upon it, within the IETF Standards Process. The license to + such derivative works not granting the ISOC and the IETF any + more rights than the license to the original Contribution, + + (D) to reproduce any trademarks, service marks or trade names + which are included in the Contribution solely in connection + with the reproduction, distribution or publication of the + Contribution and derivative works thereof as permitted by + this paragraph. When reproducing Contributions, the IETF + will preserve trademark and service mark identifiers used by + the Contributor of the Contribution, including (TM) and (R) + where appropriate, and + + (E) to extract, copy, publish, display, distribute, modify and + incorporate into other works, for any purpose (and not + limited to use within the IETF Standards Process) any + executable code or code fragments that are included in any + IETF Document (such as MIB and PIB modules), subject to the + requirements of Section 5 (it also being understood that the + licenses granted under this paragraph (E) shall not be deemed + to grant any right under any patent, patent application or + + + +Bradner Best Current Practice [Page 6] + +RFC 3667 IETF Rights in Submissions February 2004 + + + other similar intellectual property right disclosed by the + Contributor under [IETF IPR]). + + b. The Contributor grants the IETF and ISOC permission to reference + the name(s) and address(es) of the Contributor(s) and of the + organization(s) s/he represents or is sponsored by (if any). + +3.4. Representations and Warranties + + With respect to each Contribution, each Contributor represents that + to the best of his or her knowledge and ability: + + a. The Contribution properly acknowledges all major Contributors. A + major Contributor is any person who has materially or + substantially contributed to the IETF Contribution. + + b. No information in the Contribution is confidential and the IETF, + ISOC, and its affiliated organizations may freely disclose any + information in the Contribution. + + c. There are no limits to the Contributor's ability to make the + grants, acknowledgments and agreements herein that are reasonably + and personally known to the Contributor. + + d. The Contributor has not intentionally included in the Contribution + any material which is defamatory or untrue or which is illegal + under the laws of the jurisdiction in which the Contributor has + his or her principal place of business or residence. + + e. All trademarks, trade names, service marks and other proprietary + names used in the Contribution that are reasonably and personally + known to the Contributor are clearly designated as such where + reasonable. + +3.5. No Duty to Publish + + The Contributor, and each named co-Contributor, acknowledges that the + IETF has no duty to publish or otherwise use or disseminate any + Contribution. The IETF reserves the right to withdraw or cease using + any Contribution that does not comply with the requirements of + Section 3.4 and Section 3.3 or 4.2. + +3.6. Trademarks + + Contributors, and each named co-Contributor, who claim trademark + rights in terms used in their IETF Contributions are requested to + state specifically what conditions apply to implementers of + + + + +Bradner Best Current Practice [Page 7] + +RFC 3667 IETF Rights in Submissions February 2004 + + + the technology relative to the use of such trademarks. Such + statements should be submitted in the same way as is done for other + intellectual property claims. (See [RFC 3668] Section 6.) + +4. Rights in RFC Editor Contributions + + The following are the rights the IETF, as the publisher of Internet- + Drafts, requires in all RFC Editor Contributions: + +4.1. Requirements from Section 3 + + All RFC Editor Contributions must meet the requirements of Sections + 3.1, 3.2, 3.4, 3.5 and 3.6. + +4.2. Granting of Rights and Permissions + + By submission of an RFC Editor Contribution, each person actually + submitting the RFC Editor Contribution, and each named co- + Contributor, is deemed to agree to the following terms and + conditions, and to grant the following rights, on his or her own + behalf and on behalf of the organization the Contributor represents + or is sponsored by (if any) when submitting the RFC Editor + Contribution. + + a. To the extent that an RFC Editor Contribution or any portion + thereof is protected by copyright and other rights of authorship, + the Contributor, and each named co-Contributor, and the + organization he or she represents or is sponsored by (if any) + grant a perpetual, irrevocable, non-exclusive, royalty-free, + world-wide right and license to the ISOC and the IETF under all + intellectual property rights in the RFC Editor Contribution for at + least the life of the Internet-Draft: + + (A) to copy, publish, display and distribute the RFC Editor + Contribution as an RFC, and + + (B) to prepare or allow the preparation of translations of the RFC + into languages other than English. + + (C) unless explicitly disallowed in the notices contained in an + RFC Editor Contribution (as per Section 5.2 below), to prepare + derivative works (other than translations) that are based on + or incorporate all or part of the RFC Editor Contribution, or + comment upon it. The license to such derivative works not + granting the ISOC and the IETF any more rights than the + license to the original RFC Editor Contribution, and + + + + + +Bradner Best Current Practice [Page 8] + +RFC 3667 IETF Rights in Submissions February 2004 + + + (D) to reproduce any trademarks, service marks or trade names + which are included in the RFC Editor Contribution solely in + connection with the reproduction, distribution or publication + of the RFC Editor Contribution and derivative works thereof as + permitted by this paragraph. When reproducing RFC Editor + Contributions, the IETF will preserve trademark and service + mark identifiers used by the Contributor of the RFC Editor + Contribution, including (TM) and (R) where appropriate. + + b. The Contributor grants the IETF and ISOC permission to reference + the name(s) and address(es) of the Contributor(s) and of the + organization(s) s/he represents or is sponsored by (if any). + +5. Notices Required in IETF Documents + + The IETF requires that certain notices and disclaimers described in + this Section 5 be reproduced verbatim in all IETF Documents + (including copies, derivative works and translations of IETF + Documents, but subject to the limited exceptions noted in Section + 5.2). This requirement protects IETF and its participants from + liabilities connected with these documents. The copyright notice + also alerts readers that the document is an IETF Document, and that + ISOC claims copyright rights to certain aspects of the document, such + as its layout, the RFC numbering convention and the prefatory + language of the document. This legend is not intended to imply that + ISOC has obtained ownership of the IETF Contribution itself, which is + retained by the author(s) or remains in the public domain, as + applicable. + + Each IETF Document must include the required notices described in + this Section 5. The required notices are the following: + + a. The IPR Disclosure Acknowledgement described in Section 5.1 + (required in all Internet-Drafts). + b. The Derivative Works Limitation described in Section 5.2 (for + specific IETF Documents only). + c. The Publication Limitation described in Section 5.3 (for specific + types of Internet-Drafts only). + d. The Copyright Notice described in Section 5.4 (for all IETF + Documents). + e. The Disclaimer described in Section 5.5 (for all IETF Documents). + + + + + + + + + + +Bradner Best Current Practice [Page 9] + +RFC 3667 IETF Rights in Submissions February 2004 + + +5.1. IPR Disclosure Acknowledgement (required in all Internet-Drafts + only) + + "By submitting this Internet-Draft, I certify that any applicable + patent or other IPR claims of which I am aware have been disclosed, + and any of which I become aware will be disclosed, in accordance with + RFC 3668." + +5.2. Derivative Works Limitation + + If the Contributor desires to eliminate the IETF's right to make + modifications and derivative works of an IETF Contribution (other + than translations), one of the two of the following notices may be + included in the Status of Memo section of an Internet-Draft and + included in a published RFC: + + a. "This document may not be modified, and derivative works of it may + not be created, except to publish it as an RFC and to translate it + into languages other than English." + + b. "This document may not be modified, and derivative works of it may + not be created." + + In the cases of MIB or PIB modules and in other cases where the + Contribution includes material that is meant to be extracted in order + to be used, the following should be appended to statement 5.2 (a) or + 5.2 (b): + + "other than to extract section XX as-is for separate use." + + Notice 5.2(a) is used if the Contributor intends for the IETF + Contribution to be published as an RFC. Notice 5.2(b) is used along + with the Publication Limitation in Section 5.3 when the Contributor + does not intend for the IETF Contribution to be published as an RFC. + + These notices may not be used with any standards-track document or + with most working group documents, except as discussed in Section 7.3 + below, since the IETF must retain change control over its documents + and the ability to augment, clarify and enhance the original IETF + Contribution in accordance with the IETF Standards Process. + + Notice 5.2(a) may be appropriate when republishing standards produced + by other (non-IETF) standards organizations, industry consortia or + companies. These are typically published as Informational RFCs, and + do not require that change control be ceded to the IETF. Basically, + documents of this type convey information for the Internet community. + + + + + +Bradner Best Current Practice [Page 10] + +RFC 3667 IETF Rights in Submissions February 2004 + + + A fuller discussion of the rationale behind these requirements is + contained in Section 7.3 below. + +5.3. Publication Limitation + + If the Contributor only wants the IETF Contribution to be made + available in an Internet-Draft (i.e., does not want the IETF + Contribution to be published as an RFC) then the Contributor may + include the following notice in the Status of Memo section of the + Internet-Draft. + + "This document may only be posted in an Internet-Draft." + + This notice can be used on IETF Contributions that are intended to + provide background information to educate and to facilitate + discussions within IETF working groups but are not intended to be + published as an RFCs. + +5.4. Copyright Notice (required for all IETF Documents) + + (Normally placed at the end of the IETF Document.) + + "Copyright (C) The Internet Society (year). This document is + subject to the rights, licenses and restrictions contained in BCP + 78, and except as set forth therein, the authors retain all their + rights." + + Additional copyright notices are not permitted in IETF Documents + except in the case where such document is the product of a joint + development effort between the IETF and another standards development + organization or the document is a republication of the work of + another standards organization. Such exceptions must be approved on + an individual basis by the IAB. + +5.5. Disclaimer (required in all IETF Documents) + + (Normally placed at the end of the IETF Document after the copyright + notice.) + + "This document and the information contained herein are provided + on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR + ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A + PARTICULAR PURPOSE." + + + + +Bradner Best Current Practice [Page 11] + +RFC 3667 IETF Rights in Submissions February 2004 + + +5.6 Exceptions + + Notwithstanding the provisions of this Section 5, in certain limited + cases an abbreviated notice may be placed on certain types of + derivative works of IETF Documents in accordance with this Section + 5.6. + + a. in MIB modules, PIB modules and similar material commonly + extracted from IETF Documents, except for material that is being + placed under IANA maintenance, the following abbreviated notice + shall be included in the body of the material that will be + extracted in lieu of the notices otherwise required by Section 5: + + "Copyright (C) The Internet Society . This version of + this MIB module is part of RFC XXXX; see the RFC itself for + full legal notices." + + When the MIB or PIB module is the initial version of a module that + is to be maintained by the IANA, the following abbreviated notice + shall be included: + + "Copyright (C) The Internet Society . The initial + version of this MIB module was published in RFC XXXX; for full + legal notices see the RFC itself. Supplementary information + may be available on + http://www.ietf.org/copyrights/ianamib.html." + + For other types of components than "MIB", substitute "MIB module" + with an appropriate identifier. In the case of MIB and PIB + modules this statement should be placed in the DESCRIPTION clause + of the MODULE-IDENTITY macro. + + Variations of these abbreviated notices are not permitted except + in cases where the material to be extracted is the product of a + joint development effort between the IETF and another standards + development organization or is a republication of the work of + another standards organization. Such variations must be approved + on an individual basis by the IAB. + + b. short excerpts of IETF Documents presented in electronic help + systems, for example, the DESCRIPTION clauses for MIB variables, + do not need to include a copyright notice. + + + + + + + + + +Bradner Best Current Practice [Page 12] + +RFC 3667 IETF Rights in Submissions February 2004 + + +6. Notices and Rights Required in RFC Editor Contributions + + Since the IETF acts as publisher of Internet Drafts, even for + Internet Drafts that are not intended to become part of the Standards + Process, the following are required in all such drafts to protect the + IETF and its processes. The RFC Editor may require additional + notices. + + a. An IPR Disclosure Acknowledgement, identical to that specified in + Section 5.1. + + b. One of the following two copyright release statements: + + A. "By submitting this Internet-Draft, I accept the provisions of + Section 3 of RFC 3667." + + B. "By submitting this Internet-Draft, I accept the provisions of + Section 4 of RFC 3667." + +7. Exposition of Why These Procedures Are the Way They Are + +7.1. Rights Granted in IETF Contributions + + The IETF/ISOC must obtain the right to publish an IETF Contribution + as an RFC or an Internet-Draft from the Contributors. + + A primary objective of this policy is to obtain from the document + authors only the non-exclusive rights that are needed to develop and + publish IETF Documents and to use the IETF Contributions in the IETF + Standards Process while leaving all other rights with the authors. + + The non-exclusive rights that the IETF needs are: + + a. the right to publish the document + b. the right to let the document be freely reproduced in the formats + that the IETF publishes it in + c. the right to let third parties translate it into languages other + than English + d. except where explicitly excluded (see Section 5.2), the right to + make derivative works within the IETF process. + e. the right to let third parties extract some logical parts, for + example MIB modules + + The authors retain all other rights, but cannot withdraw the above + rights from the IETF/ISOC. + + + + + + +Bradner Best Current Practice [Page 13] + +RFC 3667 IETF Rights in Submissions February 2004 + + +7.2. Rights to use Contributed Material + + Because, under the laws of most countries and applicable + international treaties, copyright rights come into existence whenever + a work of authorship is created (but see Section 8 below regarding + public domain documents), and IETF cannot make use of IETF + Contributions if it does not have sufficient rights with respect to + these copyright rights, it is important that the IETF receive + assurances from all Contributors that they have the authority to + grant the IETF the rights that they claim to grant. Without this + assurance, IETF and its participants would run a greater risk of + liability to the owners of these rights. + + To this end, IETF asks Contributors to give the assurances in Section + 3.4 above. These assurances are requested, however, only to the + extent of the Contributor's reasonable and personal knowledge. (See + Section 1(l)) + +7.3. Right to Produce Derivative Works + + The IETF needs to be able to evolve IETF Documents in response to + experience gained in the deployment of the technologies described in + such IETF Documents, to incorporate developments in research and to + react to changing conditions on the Internet and other IP networks. + In order to do this the IETF must be able to produce derivatives of + its documents; thus the IETF must obtain the right from Contributors + to produce derivative works. Note though that the IETF only requires + this right for the production of derivative works within the IETF + Standards Process. The IETF does not need, nor does it obtain, the + right to let derivative works be created outside of the IETF + Standards Process other than as noted in Section 3.3 (E). + + The right to produce derivative works is required for all IETF + standards track documents and for most IETF non-standards track + documents. There are two exceptions to this requirement: documents + describing proprietary technologies and documents that are + republications of the work of other standards organizations. + + The right to produce derivative works must be granted in order for an + IETF working group to accept an IETF Contribution as a working group + document or otherwise work on it. For non-working group IETF + Contributions where the Contributor requests publication as a + standards track RFC the right to produce derivative works must be + granted before the IESG will issue an IETF Last-Call and, for most + non-standards track non-working group IETF Contributions, before the + IESG will consider the Internet-Draft for publication. + + + + + +Bradner Best Current Practice [Page 14] + +RFC 3667 IETF Rights in Submissions February 2004 + + + Occasionally a Contributor may not want to grant publication rights + or the right to produce derivative works before finding out if an + IETF Contribution has been accepted for development in the IETF + Standards Process. In these cases the Contributor may include the + Derivative Works Limitation described in Section 5.2 and the + Publication Limitation described in Section 5.3 in their IETF + Contribution. A working group can discuss the Internet-Draft with + the aim to decide if it should become a working group document, even + though the right to produce derivative works or to publish the IETF + Contribution as an RFC has not yet been granted. If the IETF + Contribution is accepted for development the Contributor must then + resubmit the IETF Contribution without the limitation notices before + a working group can formally adopt the IETF Contribution as a working + group document. + + The IETF has historically encouraged organizations to publish details + of their technologies, even when the technologies are proprietary, + because understanding how existing technology is being used helps + when developing new technology. But organizations that publish + information about proprietary technologies are frequently not willing + to have the IETF produce revisions of the technologies and then claim + that the IETF version is the "new version" of the organization's + technology. Organizations that feel this way can specify that an IETF + Contribution can be published with the other rights granted under + this document but may withhold the right to produce derivative works + other than translations. The right to produce translations is + required before any IETF Contribution can be published as an RFC to + ensure the widest possible distribution of the material in RFCs. + + In addition, IETF Documents frequently make normative references to + standards or recommendations developed by other standards + organizations. Since the publications of some standards organizations + are not public documents, it can be quite helpful to the IETF to + republish, with the permission of the other standards organization, + some of these documents as RFCs so that the IETF community can have + open access to them to better understand what they are referring to. + In these cases the RFCs can be published without the right for the + IETF to produce derivative works. + + In both of the above cases in which the production of derivative + works is excluded, the Contributor must include a special legend in + the IETF Contribution, as specified in Section 5.2, in order to + notify IETF participants about this restriction. + + + + + + + + +Bradner Best Current Practice [Page 15] + +RFC 3667 IETF Rights in Submissions February 2004 + + +7.4. Rights to Use Trademarks + + Contributors may wish to seek trademark or service mark protection on + any terms that are coined or used in their IETF Contributions. IETF + makes no judgment about the validity of any such trademark rights. + However, the IETF requires each Contributor, under the licenses + described in Section 3.3 above, to grant IETF a perpetual license to + use any such trademarks or service marks solely in exercising its + rights to reproduce, publish and modify the IETF Contribution. This + license does not authorize any IETF participant to use any trademark + or service mark in connection with any product or service offering, + but only in the context of IETF Documents and discussions. + +7.5. Who Does This Apply To? + + Rights and licenses granted to the IETF under this document are + granted to all individuals noted in Section 1(a), irrespective of + their employment or institutional affiliation. However, these + licenses do not extend broadly to the employers, sponsors or + institutions of such individuals, nor do they authorize the + individuals to exercise any rights outside the specific context of + the IETF Standards Process. + +8. Contributions Not Subject to Copyright + + Certain documents, including those produced by the U.S. government + and those which are in the public domain, may not be protected by the + same copyright and other legal rights as other documents. + Nevertheless, we ask each Contributor to grant to the IETF the same + rights as he or she would grant, and to make the same + representations, as though the IETF Contribution were protected by + the same legal rights as other documents, and as though the + Contributor could be able to grant these rights. We ask for these + grants and representations only to the extent that the Contribution + may be protected. We believe they are necessary to protect the ISOC, + the IETF, the IETF Standards Process and all IETF participants, and + also because the IETF does not have the resources or wherewithal to + make any independent investigation as to the actual proprietary + status of any document submitted to it. + +9. Security Considerations + + This memo relates to IETF process, not any particular technology. + There are security considerations when adopting any technology, but + there are no known issues of security with IETF Contribution rights + policies. + + + + + +Bradner Best Current Practice [Page 16] + +RFC 3667 IETF Rights in Submissions February 2004 + + +10. References + +10.1. Normative References + + [RFC 2026] Bradner, S., Ed, "The Internet Standards Process -- + Revision 3", BCP 9, RFC 2026, October 1996. + + [RFC 3668] Bradner, S., Ed., "Intellectual Property Rights in IETF + Technology", BCP 79, RFC 3668, February 2004. + +10.2. Informative References + + [Berne] "Berne Convention for the Protection of Literary and + Artistic Work", + http://www.wipo.int/treaties/ip/berne/index.html + +11. Acknowledgements + + The editor would like to acknowledge the help of the IETF IPR Working + Group and, in particular the help of Jorge Contreras of Hale and Dorr + for his careful legal reviews of this and other IETF IPR-related and + process documents. The editor would also like to acknowledge the + extensive help John Klensin provided during the development of the + document. + +12. Editor's Address + + Scott Bradner + Harvard University + 29 Oxford St. + Cambridge MA, 02138 + + Phone: +1 617 495 3864 + EMail: sob@harvard.edu + + + + + + + + + + + + + + + + + +Bradner Best Current Practice [Page 17] + +RFC 3667 IETF Rights in Submissions February 2004 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (2004). This document is subject + to the rights, licenses and restrictions contained in BCP 78 and + except as set forth therein, the authors retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE + INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed + to pertain to the implementation or use of the technology + described in this document or the extent to which any license + under such rights might or might not be available; nor does it + represent that it has made any independent effort to identify any + such rights. Information on the procedures with respect to + rights in RFC documents can be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use + of such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository + at http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention + any copyrights, patents or patent applications, or other + proprietary rights that may cover technology that may be required + to implement this standard. Please address the information to the + IETF at ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + +Bradner Best Current Practice [Page 18] + diff --git a/docs/standards/references/rfc3986.txt b/docs/standards/references/rfc3986.txt new file mode 100644 index 0000000..c56ed4e --- /dev/null +++ b/docs/standards/references/rfc3986.txt @@ -0,0 +1,3419 @@ + + + + + + +Network Working Group T. Berners-Lee +Request for Comments: 3986 W3C/MIT +STD: 66 R. Fielding +Updates: 1738 Day Software +Obsoletes: 2732, 2396, 1808 L. Masinter +Category: Standards Track Adobe Systems + January 2005 + + + Uniform Resource Identifier (URI): Generic Syntax + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + A Uniform Resource Identifier (URI) is a compact sequence of + characters that identifies an abstract or physical resource. This + specification defines the generic URI syntax and a process for + resolving URI references that might be in relative form, along with + guidelines and security considerations for the use of URIs on the + Internet. The URI syntax defines a grammar that is a superset of all + valid URIs, allowing an implementation to parse the common components + of a URI reference without knowing the scheme-specific requirements + of every possible identifier. This specification does not define a + generative grammar for URIs; that task is performed by the individual + specifications of each URI scheme. + + + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 1] + +RFC 3986 URI Generic Syntax January 2005 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1. Overview of URIs . . . . . . . . . . . . . . . . . . . . 4 + 1.1.1. Generic Syntax . . . . . . . . . . . . . . . . . 6 + 1.1.2. Examples . . . . . . . . . . . . . . . . . . . . 7 + 1.1.3. URI, URL, and URN . . . . . . . . . . . . . . . 7 + 1.2. Design Considerations . . . . . . . . . . . . . . . . . 8 + 1.2.1. Transcription . . . . . . . . . . . . . . . . . 8 + 1.2.2. Separating Identification from Interaction . . . 9 + 1.2.3. Hierarchical Identifiers . . . . . . . . . . . . 10 + 1.3. Syntax Notation . . . . . . . . . . . . . . . . . . . . 11 + 2. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 2.1. Percent-Encoding . . . . . . . . . . . . . . . . . . . . 12 + 2.2. Reserved Characters . . . . . . . . . . . . . . . . . . 12 + 2.3. Unreserved Characters . . . . . . . . . . . . . . . . . 13 + 2.4. When to Encode or Decode . . . . . . . . . . . . . . . . 14 + 2.5. Identifying Data . . . . . . . . . . . . . . . . . . . . 14 + 3. Syntax Components . . . . . . . . . . . . . . . . . . . . . . 16 + 3.1. Scheme . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 3.2. Authority . . . . . . . . . . . . . . . . . . . . . . . 17 + 3.2.1. User Information . . . . . . . . . . . . . . . . 18 + 3.2.2. Host . . . . . . . . . . . . . . . . . . . . . . 18 + 3.2.3. Port . . . . . . . . . . . . . . . . . . . . . . 22 + 3.3. Path . . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 3.4. Query . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 3.5. Fragment . . . . . . . . . . . . . . . . . . . . . . . . 24 + 4. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 4.1. URI Reference . . . . . . . . . . . . . . . . . . . . . 25 + 4.2. Relative Reference . . . . . . . . . . . . . . . . . . . 26 + 4.3. Absolute URI . . . . . . . . . . . . . . . . . . . . . . 27 + 4.4. Same-Document Reference . . . . . . . . . . . . . . . . 27 + 4.5. Suffix Reference . . . . . . . . . . . . . . . . . . . . 27 + 5. Reference Resolution . . . . . . . . . . . . . . . . . . . . . 28 + 5.1. Establishing a Base URI . . . . . . . . . . . . . . . . 28 + 5.1.1. Base URI Embedded in Content . . . . . . . . . . 29 + 5.1.2. Base URI from the Encapsulating Entity . . . . . 29 + 5.1.3. Base URI from the Retrieval URI . . . . . . . . 30 + 5.1.4. Default Base URI . . . . . . . . . . . . . . . . 30 + 5.2. Relative Resolution . . . . . . . . . . . . . . . . . . 30 + 5.2.1. Pre-parse the Base URI . . . . . . . . . . . . . 31 + 5.2.2. Transform References . . . . . . . . . . . . . . 31 + 5.2.3. Merge Paths . . . . . . . . . . . . . . . . . . 32 + 5.2.4. Remove Dot Segments . . . . . . . . . . . . . . 33 + 5.3. Component Recomposition . . . . . . . . . . . . . . . . 35 + 5.4. Reference Resolution Examples . . . . . . . . . . . . . 35 + 5.4.1. Normal Examples . . . . . . . . . . . . . . . . 36 + 5.4.2. Abnormal Examples . . . . . . . . . . . . . . . 36 + + + +Berners-Lee, et al. Standards Track [Page 2] + +RFC 3986 URI Generic Syntax January 2005 + + + 6. Normalization and Comparison . . . . . . . . . . . . . . . . . 38 + 6.1. Equivalence . . . . . . . . . . . . . . . . . . . . . . 38 + 6.2. Comparison Ladder . . . . . . . . . . . . . . . . . . . 39 + 6.2.1. Simple String Comparison . . . . . . . . . . . . 39 + 6.2.2. Syntax-Based Normalization . . . . . . . . . . . 40 + 6.2.3. Scheme-Based Normalization . . . . . . . . . . . 41 + 6.2.4. Protocol-Based Normalization . . . . . . . . . . 42 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 43 + 7.1. Reliability and Consistency . . . . . . . . . . . . . . 43 + 7.2. Malicious Construction . . . . . . . . . . . . . . . . . 43 + 7.3. Back-End Transcoding . . . . . . . . . . . . . . . . . . 44 + 7.4. Rare IP Address Formats . . . . . . . . . . . . . . . . 45 + 7.5. Sensitive Information . . . . . . . . . . . . . . . . . 45 + 7.6. Semantic Attacks . . . . . . . . . . . . . . . . . . . . 45 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 46 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 46 + 10.2. Informative References . . . . . . . . . . . . . . . . . 47 + A. Collected ABNF for URI . . . . . . . . . . . . . . . . . . . . 49 + B. Parsing a URI Reference with a Regular Expression . . . . . . 50 + C. Delimiting a URI in Context . . . . . . . . . . . . . . . . . 51 + D. Changes from RFC 2396 . . . . . . . . . . . . . . . . . . . . 53 + D.1. Additions . . . . . . . . . . . . . . . . . . . . . . . 53 + D.2. Modifications . . . . . . . . . . . . . . . . . . . . . 53 + Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 60 + Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 61 + + + + + + + + + + + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 3] + +RFC 3986 URI Generic Syntax January 2005 + + +1. Introduction + + A Uniform Resource Identifier (URI) provides a simple and extensible + means for identifying a resource. This specification of URI syntax + and semantics is derived from concepts introduced by the World Wide + Web global information initiative, whose use of these identifiers + dates from 1990 and is described in "Universal Resource Identifiers + in WWW" [RFC1630]. The syntax is designed to meet the + recommendations laid out in "Functional Recommendations for Internet + Resource Locators" [RFC1736] and "Functional Requirements for Uniform + Resource Names" [RFC1737]. + + This document obsoletes [RFC2396], which merged "Uniform Resource + Locators" [RFC1738] and "Relative Uniform Resource Locators" + [RFC1808] in order to define a single, generic syntax for all URIs. + It obsoletes [RFC2732], which introduced syntax for an IPv6 address. + It excludes portions of RFC 1738 that defined the specific syntax of + individual URI schemes; those portions will be updated as separate + documents. The process for registration of new URI schemes is + defined separately by [BCP35]. Advice for designers of new URI + schemes can be found in [RFC2718]. All significant changes from RFC + 2396 are noted in Appendix D. + + This specification uses the terms "character" and "coded character + set" in accordance with the definitions provided in [BCP19], and + "character encoding" in place of what [BCP19] refers to as a + "charset". + +1.1. Overview of URIs + + URIs are characterized as follows: + + Uniform + + Uniformity provides several benefits. It allows different types + of resource identifiers to be used in the same context, even when + the mechanisms used to access those resources may differ. It + allows uniform semantic interpretation of common syntactic + conventions across different types of resource identifiers. It + allows introduction of new types of resource identifiers without + interfering with the way that existing identifiers are used. It + allows the identifiers to be reused in many different contexts, + thus permitting new applications or protocols to leverage a pre- + existing, large, and widely used set of resource identifiers. + + + + + + + +Berners-Lee, et al. Standards Track [Page 4] + +RFC 3986 URI Generic Syntax January 2005 + + + Resource + + This specification does not limit the scope of what might be a + resource; rather, the term "resource" is used in a general sense + for whatever might be identified by a URI. Familiar examples + include an electronic document, an image, a source of information + with a consistent purpose (e.g., "today's weather report for Los + Angeles"), a service (e.g., an HTTP-to-SMS gateway), and a + collection of other resources. A resource is not necessarily + accessible via the Internet; e.g., human beings, corporations, and + bound books in a library can also be resources. Likewise, + abstract concepts can be resources, such as the operators and + operands of a mathematical equation, the types of a relationship + (e.g., "parent" or "employee"), or numeric values (e.g., zero, + one, and infinity). + + Identifier + + An identifier embodies the information required to distinguish + what is being identified from all other things within its scope of + identification. Our use of the terms "identify" and "identifying" + refer to this purpose of distinguishing one resource from all + other resources, regardless of how that purpose is accomplished + (e.g., by name, address, or context). These terms should not be + mistaken as an assumption that an identifier defines or embodies + the identity of what is referenced, though that may be the case + for some identifiers. Nor should it be assumed that a system + using URIs will access the resource identified: in many cases, + URIs are used to denote resources without any intention that they + be accessed. Likewise, the "one" resource identified might not be + singular in nature (e.g., a resource might be a named set or a + mapping that varies over time). + + A URI is an identifier consisting of a sequence of characters + matching the syntax rule named in Section 3. It enables + uniform identification of resources via a separately defined + extensible set of naming schemes (Section 3.1). How that + identification is accomplished, assigned, or enabled is delegated to + each scheme specification. + + This specification does not place any limits on the nature of a + resource, the reasons why an application might seek to refer to a + resource, or the kinds of systems that might use URIs for the sake of + identifying resources. This specification does not require that a + URI persists in identifying the same resource over time, though that + is a common goal of all URI schemes. Nevertheless, nothing in this + + + + + +Berners-Lee, et al. Standards Track [Page 5] + +RFC 3986 URI Generic Syntax January 2005 + + + specification prevents an application from limiting itself to + particular types of resources, or to a subset of URIs that maintains + characteristics desired by that application. + + URIs have a global scope and are interpreted consistently regardless + of context, though the result of that interpretation may be in + relation to the end-user's context. For example, "http://localhost/" + has the same interpretation for every user of that reference, even + though the network interface corresponding to "localhost" may be + different for each end-user: interpretation is independent of access. + However, an action made on the basis of that reference will take + place in relation to the end-user's context, which implies that an + action intended to refer to a globally unique thing must use a URI + that distinguishes that resource from all other things. URIs that + identify in relation to the end-user's local context should only be + used when the context itself is a defining aspect of the resource, + such as when an on-line help manual refers to a file on the end- + user's file system (e.g., "file:///etc/hosts"). + +1.1.1. Generic Syntax + + Each URI begins with a scheme name, as defined in Section 3.1, that + refers to a specification for assigning identifiers within that + scheme. As such, the URI syntax is a federated and extensible naming + system wherein each scheme's specification may further restrict the + syntax and semantics of identifiers using that scheme. + + This specification defines those elements of the URI syntax that are + required of all URI schemes or are common to many URI schemes. It + thus defines the syntax and semantics needed to implement a scheme- + independent parsing mechanism for URI references, by which the + scheme-dependent handling of a URI can be postponed until the + scheme-dependent semantics are needed. Likewise, protocols and data + formats that make use of URI references can refer to this + specification as a definition for the range of syntax allowed for all + URIs, including those schemes that have yet to be defined. This + decouples the evolution of identification schemes from the evolution + of protocols, data formats, and implementations that make use of + URIs. + + A parser of the generic URI syntax can parse any URI reference into + its major components. Once the scheme is determined, further + scheme-specific parsing can be performed on the components. In other + words, the URI generic syntax is a superset of the syntax of all URI + schemes. + + + + + + +Berners-Lee, et al. Standards Track [Page 6] + +RFC 3986 URI Generic Syntax January 2005 + + +1.1.2. Examples + + The following example URIs illustrate several URI schemes and + variations in their common syntax components: + + ftp://ftp.is.co.za/rfc/rfc1808.txt + + http://www.ietf.org/rfc/rfc2396.txt + + ldap://[2001:db8::7]/c=GB?objectClass?one + + mailto:John.Doe@example.com + + news:comp.infosystems.www.servers.unix + + tel:+1-816-555-1212 + + telnet://192.0.2.16:80/ + + urn:oasis:names:specification:docbook:dtd:xml:4.1.2 + + +1.1.3. URI, URL, and URN + + A URI can be further classified as a locator, a name, or both. The + term "Uniform Resource Locator" (URL) refers to the subset of URIs + that, in addition to identifying a resource, provide a means of + locating the resource by describing its primary access mechanism + (e.g., its network "location"). The term "Uniform Resource Name" + (URN) has been used historically to refer to both URIs under the + "urn" scheme [RFC2141], which are required to remain globally unique + and persistent even when the resource ceases to exist or becomes + unavailable, and to any other URI with the properties of a name. + + An individual scheme does not have to be classified as being just one + of "name" or "locator". Instances of URIs from any given scheme may + have the characteristics of names or locators or both, often + depending on the persistence and care in the assignment of + identifiers by the naming authority, rather than on any quality of + the scheme. Future specifications and related documentation should + use the general term "URI" rather than the more restrictive terms + "URL" and "URN" [RFC3305]. + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 7] + +RFC 3986 URI Generic Syntax January 2005 + + +1.2. Design Considerations + +1.2.1. Transcription + + The URI syntax has been designed with global transcription as one of + its main considerations. A URI is a sequence of characters from a + very limited set: the letters of the basic Latin alphabet, digits, + and a few special characters. A URI may be represented in a variety + of ways; e.g., ink on paper, pixels on a screen, or a sequence of + character encoding octets. The interpretation of a URI depends only + on the characters used and not on how those characters are + represented in a network protocol. + + The goal of transcription can be described by a simple scenario. + Imagine two colleagues, Sam and Kim, sitting in a pub at an + international conference and exchanging research ideas. Sam asks Kim + for a location to get more information, so Kim writes the URI for the + research site on a napkin. Upon returning home, Sam takes out the + napkin and types the URI into a computer, which then retrieves the + information to which Kim referred. + + There are several design considerations revealed by the scenario: + + o A URI is a sequence of characters that is not always represented + as a sequence of octets. + + o A URI might be transcribed from a non-network source and thus + should consist of characters that are most likely able to be + entered into a computer, within the constraints imposed by + keyboards (and related input devices) across languages and + locales. + + o A URI often has to be remembered by people, and it is easier for + people to remember a URI when it consists of meaningful or + familiar components. + + These design considerations are not always in alignment. For + example, it is often the case that the most meaningful name for a URI + component would require characters that cannot be typed into some + systems. The ability to transcribe a resource identifier from one + medium to another has been considered more important than having a + URI consist of the most meaningful of components. + + In local or regional contexts and with improving technology, users + might benefit from being able to use a wider range of characters; + such use is not defined by this specification. Percent-encoded + octets (Section 2.1) may be used within a URI to represent characters + outside the range of the US-ASCII coded character set if this + + + +Berners-Lee, et al. Standards Track [Page 8] + +RFC 3986 URI Generic Syntax January 2005 + + + representation is allowed by the scheme or by the protocol element in + which the URI is referenced. Such a definition should specify the + character encoding used to map those characters to octets prior to + being percent-encoded for the URI. + +1.2.2. Separating Identification from Interaction + + A common misunderstanding of URIs is that they are only used to refer + to accessible resources. The URI itself only provides + identification; access to the resource is neither guaranteed nor + implied by the presence of a URI. Instead, any operation associated + with a URI reference is defined by the protocol element, data format + attribute, or natural language text in which it appears. + + Given a URI, a system may attempt to perform a variety of operations + on the resource, as might be characterized by words such as "access", + "update", "replace", or "find attributes". Such operations are + defined by the protocols that make use of URIs, not by this + specification. However, we do use a few general terms for describing + common operations on URIs. URI "resolution" is the process of + determining an access mechanism and the appropriate parameters + necessary to dereference a URI; this resolution may require several + iterations. To use that access mechanism to perform an action on the + URI's resource is to "dereference" the URI. + + When URIs are used within information retrieval systems to identify + sources of information, the most common form of URI dereference is + "retrieval": making use of a URI in order to retrieve a + representation of its associated resource. A "representation" is a + sequence of octets, along with representation metadata describing + those octets, that constitutes a record of the state of the resource + at the time when the representation is generated. Retrieval is + achieved by a process that might include using the URI as a cache key + to check for a locally cached representation, resolution of the URI + to determine an appropriate access mechanism (if any), and + dereference of the URI for the sake of applying a retrieval + operation. Depending on the protocols used to perform the retrieval, + additional information might be supplied about the resource (resource + metadata) and its relation to other resources. + + URI references in information retrieval systems are designed to be + late-binding: the result of an access is generally determined when it + is accessed and may vary over time or due to other aspects of the + interaction. These references are created in order to be used in the + future: what is being identified is not some specific result that was + obtained in the past, but rather some characteristic that is expected + to be true for future results. In such cases, the resource referred + to by the URI is actually a sameness of characteristics as observed + + + +Berners-Lee, et al. Standards Track [Page 9] + +RFC 3986 URI Generic Syntax January 2005 + + + over time, perhaps elucidated by additional comments or assertions + made by the resource provider. + + Although many URI schemes are named after protocols, this does not + imply that use of these URIs will result in access to the resource + via the named protocol. URIs are often used simply for the sake of + identification. Even when a URI is used to retrieve a representation + of a resource, that access might be through gateways, proxies, + caches, and name resolution services that are independent of the + protocol associated with the scheme name. The resolution of some + URIs may require the use of more than one protocol (e.g., both DNS + and HTTP are typically used to access an "http" URI's origin server + when a representation isn't found in a local cache). + +1.2.3. Hierarchical Identifiers + + The URI syntax is organized hierarchically, with components listed in + order of decreasing significance from left to right. For some URI + schemes, the visible hierarchy is limited to the scheme itself: + everything after the scheme component delimiter (":") is considered + opaque to URI processing. Other URI schemes make the hierarchy + explicit and visible to generic parsing algorithms. + + The generic syntax uses the slash ("/"), question mark ("?"), and + number sign ("#") characters to delimit components that are + significant to the generic parser's hierarchical interpretation of an + identifier. In addition to aiding the readability of such + identifiers through the consistent use of familiar syntax, this + uniform representation of hierarchy across naming schemes allows + scheme-independent references to be made relative to that hierarchy. + + It is often the case that a group or "tree" of documents has been + constructed to serve a common purpose, wherein the vast majority of + URI references in these documents point to resources within the tree + rather than outside it. Similarly, documents located at a particular + site are much more likely to refer to other resources at that site + than to resources at remote sites. Relative referencing of URIs + allows document trees to be partially independent of their location + and access scheme. For instance, it is possible for a single set of + hypertext documents to be simultaneously accessible and traversable + via each of the "file", "http", and "ftp" schemes if the documents + refer to each other with relative references. Furthermore, such + document trees can be moved, as a whole, without changing any of the + relative references. + + A relative reference (Section 4.2) refers to a resource by describing + the difference within a hierarchical name space between the reference + context and the target URI. The reference resolution algorithm, + + + +Berners-Lee, et al. Standards Track [Page 10] + +RFC 3986 URI Generic Syntax January 2005 + + + presented in Section 5, defines how such a reference is transformed + to the target URI. As relative references can only be used within + the context of a hierarchical URI, designers of new URI schemes + should use a syntax consistent with the generic syntax's hierarchical + components unless there are compelling reasons to forbid relative + referencing within that scheme. + + NOTE: Previous specifications used the terms "partial URI" and + "relative URI" to denote a relative reference to a URI. As some + readers misunderstood those terms to mean that relative URIs are a + subset of URIs rather than a method of referencing URIs, this + specification simply refers to them as relative references. + + All URI references are parsed by generic syntax parsers when used. + However, because hierarchical processing has no effect on an absolute + URI used in a reference unless it contains one or more dot-segments + (complete path segments of "." or "..", as described in Section 3.3), + URI scheme specifications can define opaque identifiers by + disallowing use of slash characters, question mark characters, and + the URIs "scheme:." and "scheme:..". + +1.3. Syntax Notation + + This specification uses the Augmented Backus-Naur Form (ABNF) + notation of [RFC2234], including the following core ABNF syntax rules + defined by that specification: ALPHA (letters), CR (carriage return), + DIGIT (decimal digits), DQUOTE (double quote), HEXDIG (hexadecimal + digits), LF (line feed), and SP (space). The complete URI syntax is + collected in Appendix A. + +2. Characters + + The URI syntax provides a method of encoding data, presumably for the + sake of identifying a resource, as a sequence of characters. The URI + characters are, in turn, frequently encoded as octets for transport + or presentation. This specification does not mandate any particular + character encoding for mapping between URI characters and the octets + used to store or transmit those characters. When a URI appears in a + protocol element, the character encoding is defined by that protocol; + without such a definition, a URI is assumed to be in the same + character encoding as the surrounding text. + + The ABNF notation defines its terminal values to be non-negative + integers (codepoints) based on the US-ASCII coded character set + [ASCII]. Because a URI is a sequence of characters, we must invert + that relation in order to understand the URI syntax. Therefore, the + + + + + +Berners-Lee, et al. Standards Track [Page 11] + +RFC 3986 URI Generic Syntax January 2005 + + + integer values used by the ABNF must be mapped back to their + corresponding characters via US-ASCII in order to complete the syntax + rules. + + A URI is composed from a limited set of characters consisting of + digits, letters, and a few graphic symbols. A reserved subset of + those characters may be used to delimit syntax components within a + URI while the remaining characters, including both the unreserved set + and those reserved characters not acting as delimiters, define each + component's identifying data. + +2.1. Percent-Encoding + + A percent-encoding mechanism is used to represent a data octet in a + component when that octet's corresponding character is outside the + allowed set or is being used as a delimiter of, or within, the + component. A percent-encoded octet is encoded as a character + triplet, consisting of the percent character "%" followed by the two + hexadecimal digits representing that octet's numeric value. For + example, "%20" is the percent-encoding for the binary octet + "00100000" (ABNF: %x20), which in US-ASCII corresponds to the space + character (SP). Section 2.4 describes when percent-encoding and + decoding is applied. + + pct-encoded = "%" HEXDIG HEXDIG + + The uppercase hexadecimal digits 'A' through 'F' are equivalent to + the lowercase digits 'a' through 'f', respectively. If two URIs + differ only in the case of hexadecimal digits used in percent-encoded + octets, they are equivalent. For consistency, URI producers and + normalizers should use uppercase hexadecimal digits for all percent- + encodings. + +2.2. Reserved Characters + + URIs include components and subcomponents that are delimited by + characters in the "reserved" set. These characters are called + "reserved" because they may (or may not) be defined as delimiters by + the generic syntax, by each scheme-specific syntax, or by the + implementation-specific syntax of a URI's dereferencing algorithm. + If data for a URI component would conflict with a reserved + character's purpose as a delimiter, then the conflicting data must be + percent-encoded before the URI is formed. + + + + + + + + +Berners-Lee, et al. Standards Track [Page 12] + +RFC 3986 URI Generic Syntax January 2005 + + + reserved = gen-delims / sub-delims + + gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + + The purpose of reserved characters is to provide a set of delimiting + characters that are distinguishable from other data within a URI. + URIs that differ in the replacement of a reserved character with its + corresponding percent-encoded octet are not equivalent. Percent- + encoding a reserved character, or decoding a percent-encoded octet + that corresponds to a reserved character, will change how the URI is + interpreted by most applications. Thus, characters in the reserved + set are protected from normalization and are therefore safe to be + used by scheme-specific and producer-specific algorithms for + delimiting data subcomponents within a URI. + + A subset of the reserved characters (gen-delims) is used as + delimiters of the generic URI components described in Section 3. A + component's ABNF syntax rule will not use the reserved or gen-delims + rule names directly; instead, each syntax rule lists the characters + allowed within that component (i.e., not delimiting it), and any of + those characters that are also in the reserved set are "reserved" for + use as subcomponent delimiters within the component. Only the most + common subcomponents are defined by this specification; other + subcomponents may be defined by a URI scheme's specification, or by + the implementation-specific syntax of a URI's dereferencing + algorithm, provided that such subcomponents are delimited by + characters in the reserved set allowed within that component. + + URI producing applications should percent-encode data octets that + correspond to characters in the reserved set unless these characters + are specifically allowed by the URI scheme to represent data in that + component. If a reserved character is found in a URI component and + no delimiting role is known for that character, then it must be + interpreted as representing the data octet corresponding to that + character's encoding in US-ASCII. + +2.3. Unreserved Characters + + Characters that are allowed in a URI but do not have a reserved + purpose are called unreserved. These include uppercase and lowercase + letters, decimal digits, hyphen, period, underscore, and tilde. + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + + + + + +Berners-Lee, et al. Standards Track [Page 13] + +RFC 3986 URI Generic Syntax January 2005 + + + URIs that differ in the replacement of an unreserved character with + its corresponding percent-encoded US-ASCII octet are equivalent: they + identify the same resource. However, URI comparison implementations + do not always perform normalization prior to comparison (see Section + 6). For consistency, percent-encoded octets in the ranges of ALPHA + (%41-%5A and %61-%7A), DIGIT (%30-%39), hyphen (%2D), period (%2E), + underscore (%5F), or tilde (%7E) should not be created by URI + producers and, when found in a URI, should be decoded to their + corresponding unreserved characters by URI normalizers. + +2.4. When to Encode or Decode + + Under normal circumstances, the only time when octets within a URI + are percent-encoded is during the process of producing the URI from + its component parts. This is when an implementation determines which + of the reserved characters are to be used as subcomponent delimiters + and which can be safely used as data. Once produced, a URI is always + in its percent-encoded form. + + When a URI is dereferenced, the components and subcomponents + significant to the scheme-specific dereferencing process (if any) + must be parsed and separated before the percent-encoded octets within + those components can be safely decoded, as otherwise the data may be + mistaken for component delimiters. The only exception is for + percent-encoded octets corresponding to characters in the unreserved + set, which can be decoded at any time. For example, the octet + corresponding to the tilde ("~") character is often encoded as "%7E" + by older URI processing implementations; the "%7E" can be replaced by + "~" without changing its interpretation. + + Because the percent ("%") character serves as the indicator for + percent-encoded octets, it must be percent-encoded as "%25" for that + octet to be used as data within a URI. Implementations must not + percent-encode or decode the same string more than once, as decoding + an already decoded string might lead to misinterpreting a percent + data octet as the beginning of a percent-encoding, or vice versa in + the case of percent-encoding an already percent-encoded string. + +2.5. Identifying Data + + URI characters provide identifying data for each of the URI + components, serving as an external interface for identification + between systems. Although the presence and nature of the URI + production interface is hidden from clients that use its URIs (and is + thus beyond the scope of the interoperability requirements defined by + this specification), it is a frequent source of confusion and errors + in the interpretation of URI character issues. Implementers have to + be aware that there are multiple character encodings involved in the + + + +Berners-Lee, et al. Standards Track [Page 14] + +RFC 3986 URI Generic Syntax January 2005 + + + production and transmission of URIs: local name and data encoding, + public interface encoding, URI character encoding, data format + encoding, and protocol encoding. + + Local names, such as file system names, are stored with a local + character encoding. URI producing applications (e.g., origin + servers) will typically use the local encoding as the basis for + producing meaningful names. The URI producer will transform the + local encoding to one that is suitable for a public interface and + then transform the public interface encoding into the restricted set + of URI characters (reserved, unreserved, and percent-encodings). + Those characters are, in turn, encoded as octets to be used as a + reference within a data format (e.g., a document charset), and such + data formats are often subsequently encoded for transmission over + Internet protocols. + + For most systems, an unreserved character appearing within a URI + component is interpreted as representing the data octet corresponding + to that character's encoding in US-ASCII. Consumers of URIs assume + that the letter "X" corresponds to the octet "01011000", and even + when that assumption is incorrect, there is no harm in making it. A + system that internally provides identifiers in the form of a + different character encoding, such as EBCDIC, will generally perform + character translation of textual identifiers to UTF-8 [STD63] (or + some other superset of the US-ASCII character encoding) at an + internal interface, thereby providing more meaningful identifiers + than those resulting from simply percent-encoding the original + octets. + + For example, consider an information service that provides data, + stored locally using an EBCDIC-based file system, to clients on the + Internet through an HTTP server. When an author creates a file with + the name "Laguna Beach" on that file system, the "http" URI + corresponding to that resource is expected to contain the meaningful + string "Laguna%20Beach". If, however, that server produces URIs by + using an overly simplistic raw octet mapping, then the result would + be a URI containing "%D3%81%87%A4%95%81@%C2%85%81%83%88". An + internal transcoding interface fixes this problem by transcoding the + local name to a superset of US-ASCII prior to producing the URI. + Naturally, proper interpretation of an incoming URI on such an + interface requires that percent-encoded octets be decoded (e.g., + "%20" to SP) before the reverse transcoding is applied to obtain the + local name. + + In some cases, the internal interface between a URI component and the + identifying data that it has been crafted to represent is much less + direct than a character encoding translation. For example, portions + of a URI might reflect a query on non-ASCII data, or numeric + + + +Berners-Lee, et al. Standards Track [Page 15] + +RFC 3986 URI Generic Syntax January 2005 + + + coordinates on a map. Likewise, a URI scheme may define components + with additional encoding requirements that are applied prior to + forming the component and producing the URI. + + When a new URI scheme defines a component that represents textual + data consisting of characters from the Universal Character Set [UCS], + the data should first be encoded as octets according to the UTF-8 + character encoding [STD63]; then only those octets that do not + correspond to characters in the unreserved set should be percent- + encoded. For example, the character A would be represented as "A", + the character LATIN CAPITAL LETTER A WITH GRAVE would be represented + as "%C3%80", and the character KATAKANA LETTER A would be represented + as "%E3%82%A2". + +3. Syntax Components + + The generic URI syntax consists of a hierarchical sequence of + components referred to as the scheme, authority, path, query, and + fragment. + + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty + + The scheme and path components are required, though the path may be + empty (no characters). When authority is present, the path must + either be empty or begin with a slash ("/") character. When + authority is not present, the path cannot begin with two slash + characters ("//"). These restrictions result in five different ABNF + rules for a path (Section 3.3), only one of which will match any + given URI reference. + + The following are two example URIs and their component parts: + + foo://example.com:8042/over/there?name=ferret#nose + \_/ \______________/\_________/ \_________/ \__/ + | | | | | + scheme authority path query fragment + | _____________________|__ + / \ / \ + urn:example:animal:ferret:nose + + + + + + + +Berners-Lee, et al. Standards Track [Page 16] + +RFC 3986 URI Generic Syntax January 2005 + + +3.1. Scheme + + Each URI begins with a scheme name that refers to a specification for + assigning identifiers within that scheme. As such, the URI syntax is + a federated and extensible naming system wherein each scheme's + specification may further restrict the syntax and semantics of + identifiers using that scheme. + + Scheme names consist of a sequence of characters beginning with a + letter and followed by any combination of letters, digits, plus + ("+"), period ("."), or hyphen ("-"). Although schemes are case- + insensitive, the canonical form is lowercase and documents that + specify schemes must do so with lowercase letters. An implementation + should accept uppercase letters as equivalent to lowercase in scheme + names (e.g., allow "HTTP" as well as "http") for the sake of + robustness but should only produce lowercase scheme names for + consistency. + + scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) + + Individual schemes are not specified by this document. The process + for registration of new URI schemes is defined separately by [BCP35]. + The scheme registry maintains the mapping between scheme names and + their specifications. Advice for designers of new URI schemes can be + found in [RFC2718]. URI scheme specifications must define their own + syntax so that all strings matching their scheme-specific syntax will + also match the grammar, as described in Section 4.3. + + When presented with a URI that violates one or more scheme-specific + restrictions, the scheme-specific resolution process should flag the + reference as an error rather than ignore the unused parts; doing so + reduces the number of equivalent URIs and helps detect abuses of the + generic syntax, which might indicate that the URI has been + constructed to mislead the user (Section 7.6). + +3.2. Authority + + Many URI schemes include a hierarchical element for a naming + authority so that governance of the name space defined by the + remainder of the URI is delegated to that authority (which may, in + turn, delegate it further). The generic syntax provides a common + means for distinguishing an authority based on a registered name or + server address, along with optional port and user information. + + The authority component is preceded by a double slash ("//") and is + terminated by the next slash ("/"), question mark ("?"), or number + sign ("#") character, or by the end of the URI. + + + + +Berners-Lee, et al. Standards Track [Page 17] + +RFC 3986 URI Generic Syntax January 2005 + + + authority = [ userinfo "@" ] host [ ":" port ] + + URI producers and normalizers should omit the ":" delimiter that + separates host from port if the port component is empty. Some + schemes do not allow the userinfo and/or port subcomponents. + + If a URI contains an authority component, then the path component + must either be empty or begin with a slash ("/") character. Non- + validating parsers (those that merely separate a URI reference into + its major components) will often ignore the subcomponent structure of + authority, treating it as an opaque string from the double-slash to + the first terminating delimiter, until such time as the URI is + dereferenced. + +3.2.1. User Information + + The userinfo subcomponent may consist of a user name and, optionally, + scheme-specific information about how to gain authorization to access + the resource. The user information, if present, is followed by a + commercial at-sign ("@") that delimits it from the host. + + userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) + + Use of the format "user:password" in the userinfo field is + deprecated. Applications should not render as clear text any data + after the first colon (":") character found within a userinfo + subcomponent unless the data after the colon is the empty string + (indicating no password). Applications may choose to ignore or + reject such data when it is received as part of a reference and + should reject the storage of such data in unencrypted form. The + passing of authentication information in clear text has proven to be + a security risk in almost every case where it has been used. + + Applications that render a URI for the sake of user feedback, such as + in graphical hypertext browsing, should render userinfo in a way that + is distinguished from the rest of a URI, when feasible. Such + rendering will assist the user in cases where the userinfo has been + misleadingly crafted to look like a trusted domain name + (Section 7.6). + +3.2.2. Host + + The host subcomponent of authority is identified by an IP literal + encapsulated within square brackets, an IPv4 address in dotted- + decimal form, or a registered name. The host subcomponent is case- + insensitive. The presence of a host subcomponent within a URI does + not imply that the scheme requires access to the given host on the + Internet. In many cases, the host syntax is used only for the sake + + + +Berners-Lee, et al. Standards Track [Page 18] + +RFC 3986 URI Generic Syntax January 2005 + + + of reusing the existing registration process created and deployed for + DNS, thus obtaining a globally unique name without the cost of + deploying another registry. However, such use comes with its own + costs: domain name ownership may change over time for reasons not + anticipated by the URI producer. In other cases, the data within the + host component identifies a registered name that has nothing to do + with an Internet host. We use the name "host" for the ABNF rule + because that is its most common purpose, not its only purpose. + + host = IP-literal / IPv4address / reg-name + + The syntax rule for host is ambiguous because it does not completely + distinguish between an IPv4address and a reg-name. In order to + disambiguate the syntax, we apply the "first-match-wins" algorithm: + If host matches the rule for IPv4address, then it should be + considered an IPv4 address literal and not a reg-name. Although host + is case-insensitive, producers and normalizers should use lowercase + for registered names and hexadecimal addresses for the sake of + uniformity, while only using uppercase letters for percent-encodings. + + A host identified by an Internet Protocol literal address, version 6 + [RFC3513] or later, is distinguished by enclosing the IP literal + within square brackets ("[" and "]"). This is the only place where + square bracket characters are allowed in the URI syntax. In + anticipation of future, as-yet-undefined IP literal address formats, + an implementation may use an optional version flag to indicate such a + format explicitly rather than rely on heuristic determination. + + IP-literal = "[" ( IPv6address / IPvFuture ) "]" + + IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) + + The version flag does not indicate the IP version; rather, it + indicates future versions of the literal format. As such, + implementations must not provide the version flag for the existing + IPv4 and IPv6 literal address forms described below. If a URI + containing an IP-literal that starts with "v" (case-insensitive), + indicating that the version flag is present, is dereferenced by an + application that does not know the meaning of that version flag, then + the application should return an appropriate error for "address + mechanism not supported". + + A host identified by an IPv6 literal address is represented inside + the square brackets without a preceding version flag. The ABNF + provided here is a translation of the text definition of an IPv6 + literal address provided in [RFC3513]. This syntax does not support + IPv6 scoped addressing zone identifiers. + + + + +Berners-Lee, et al. Standards Track [Page 19] + +RFC 3986 URI Generic Syntax January 2005 + + + A 128-bit IPv6 address is divided into eight 16-bit pieces. Each + piece is represented numerically in case-insensitive hexadecimal, + using one to four hexadecimal digits (leading zeroes are permitted). + The eight encoded pieces are given most-significant first, separated + by colon characters. Optionally, the least-significant two pieces + may instead be represented in IPv4 address textual format. A + sequence of one or more consecutive zero-valued 16-bit pieces within + the address may be elided, omitting all their digits and leaving + exactly two consecutive colons in their place to mark the elision. + + IPv6address = 6( h16 ":" ) ls32 + / "::" 5( h16 ":" ) ls32 + / [ h16 ] "::" 4( h16 ":" ) ls32 + / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 + / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 + / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 + / [ *4( h16 ":" ) h16 ] "::" ls32 + / [ *5( h16 ":" ) h16 ] "::" h16 + / [ *6( h16 ":" ) h16 ] "::" + + ls32 = ( h16 ":" h16 ) / IPv4address + ; least-significant 32 bits of address + + h16 = 1*4HEXDIG + ; 16 bits of address represented in hexadecimal + + A host identified by an IPv4 literal address is represented in + dotted-decimal notation (a sequence of four decimal numbers in the + range 0 to 255, separated by "."), as described in [RFC1123] by + reference to [RFC0952]. Note that other forms of dotted notation may + be interpreted on some platforms, as described in Section 7.4, but + only the dotted-decimal form of four octets is allowed by this + grammar. + + IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet + + dec-octet = DIGIT ; 0-9 + / %x31-39 DIGIT ; 10-99 + / "1" 2DIGIT ; 100-199 + / "2" %x30-34 DIGIT ; 200-249 + / "25" %x30-35 ; 250-255 + + A host identified by a registered name is a sequence of characters + usually intended for lookup within a locally defined host or service + name registry, though the URI's scheme-specific semantics may require + that a specific registry (or fixed name table) be used instead. The + most common name registry mechanism is the Domain Name System (DNS). + A registered name intended for lookup in the DNS uses the syntax + + + +Berners-Lee, et al. Standards Track [Page 20] + +RFC 3986 URI Generic Syntax January 2005 + + + defined in Section 3.5 of [RFC1034] and Section 2.1 of [RFC1123]. + Such a name consists of a sequence of domain labels separated by ".", + each domain label starting and ending with an alphanumeric character + and possibly also containing "-" characters. The rightmost domain + label of a fully qualified domain name in DNS may be followed by a + single "." and should be if it is necessary to distinguish between + the complete domain name and some local domain. + + reg-name = *( unreserved / pct-encoded / sub-delims ) + + If the URI scheme defines a default for host, then that default + applies when the host subcomponent is undefined or when the + registered name is empty (zero length). For example, the "file" URI + scheme is defined so that no authority, an empty host, and + "localhost" all mean the end-user's machine, whereas the "http" + scheme considers a missing authority or empty host invalid. + + This specification does not mandate a particular registered name + lookup technology and therefore does not restrict the syntax of reg- + name beyond what is necessary for interoperability. Instead, it + delegates the issue of registered name syntax conformance to the + operating system of each application performing URI resolution, and + that operating system decides what it will allow for the purpose of + host identification. A URI resolution implementation might use DNS, + host tables, yellow pages, NetInfo, WINS, or any other system for + lookup of registered names. However, a globally scoped naming + system, such as DNS fully qualified domain names, is necessary for + URIs intended to have global scope. URI producers should use names + that conform to the DNS syntax, even when use of DNS is not + immediately apparent, and should limit these names to no more than + 255 characters in length. + + The reg-name syntax allows percent-encoded octets in order to + represent non-ASCII registered names in a uniform way that is + independent of the underlying name resolution technology. Non-ASCII + characters must first be encoded according to UTF-8 [STD63], and then + each octet of the corresponding UTF-8 sequence must be percent- + encoded to be represented as URI characters. URI producing + applications must not use percent-encoding in host unless it is used + to represent a UTF-8 character sequence. When a non-ASCII registered + name represents an internationalized domain name intended for + resolution via the DNS, the name must be transformed to the IDNA + encoding [RFC3490] prior to name lookup. URI producers should + provide these registered names in the IDNA encoding, rather than a + percent-encoding, if they wish to maximize interoperability with + legacy URI resolvers. + + + + + +Berners-Lee, et al. Standards Track [Page 21] + +RFC 3986 URI Generic Syntax January 2005 + + +3.2.3. Port + + The port subcomponent of authority is designated by an optional port + number in decimal following the host and delimited from it by a + single colon (":") character. + + port = *DIGIT + + A scheme may define a default port. For example, the "http" scheme + defines a default port of "80", corresponding to its reserved TCP + port number. The type of port designated by the port number (e.g., + TCP, UDP, SCTP) is defined by the URI scheme. URI producers and + normalizers should omit the port component and its ":" delimiter if + port is empty or if its value would be the same as that of the + scheme's default. + +3.3. Path + + The path component contains data, usually organized in hierarchical + form, that, along with data in the non-hierarchical query component + (Section 3.4), serves to identify a resource within the scope of the + URI's scheme and naming authority (if any). The path is terminated + by the first question mark ("?") or number sign ("#") character, or + by the end of the URI. + + If a URI contains an authority component, then the path component + must either be empty or begin with a slash ("/") character. If a URI + does not contain an authority component, then the path cannot begin + with two slash characters ("//"). In addition, a URI reference + (Section 4.1) may be a relative-path reference, in which case the + first path segment cannot contain a colon (":") character. The ABNF + requires five separate rules to disambiguate these cases, only one of + which will match the path substring within a given URI reference. We + use the generic term "path component" to describe the URI substring + matched by the parser to one of these rules. + + path = path-abempty ; begins with "/" or is empty + / path-absolute ; begins with "/" but not "//" + / path-noscheme ; begins with a non-colon segment + / path-rootless ; begins with a segment + / path-empty ; zero characters + + path-abempty = *( "/" segment ) + path-absolute = "/" [ segment-nz *( "/" segment ) ] + path-noscheme = segment-nz-nc *( "/" segment ) + path-rootless = segment-nz *( "/" segment ) + path-empty = 0 + + + + +Berners-Lee, et al. Standards Track [Page 22] + +RFC 3986 URI Generic Syntax January 2005 + + + segment = *pchar + segment-nz = 1*pchar + segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) + ; non-zero-length segment without any colon ":" + + pchar = unreserved / pct-encoded / sub-delims / ":" / "@" + + A path consists of a sequence of path segments separated by a slash + ("/") character. A path is always defined for a URI, though the + defined path may be empty (zero length). Use of the slash character + to indicate hierarchy is only required when a URI will be used as the + context for relative references. For example, the URI + has a path of "fred@example.com", whereas + the URI has an empty path. + + The path segments "." and "..", also known as dot-segments, are + defined for relative reference within the path name hierarchy. They + are intended for use at the beginning of a relative-path reference + (Section 4.2) to indicate relative position within the hierarchical + tree of names. This is similar to their role within some operating + systems' file directory structures to indicate the current directory + and parent directory, respectively. However, unlike in a file + system, these dot-segments are only interpreted within the URI path + hierarchy and are removed as part of the resolution process (Section + 5.2). + + Aside from dot-segments in hierarchical paths, a path segment is + considered opaque by the generic syntax. URI producing applications + often use the reserved characters allowed in a segment to delimit + scheme-specific or dereference-handler-specific subcomponents. For + example, the semicolon (";") and equals ("=") reserved characters are + often used to delimit parameters and parameter values applicable to + that segment. The comma (",") reserved character is often used for + similar purposes. For example, one URI producer might use a segment + such as "name;v=1.1" to indicate a reference to version 1.1 of + "name", whereas another might use a segment such as "name,1.1" to + indicate the same. Parameter types may be defined by scheme-specific + semantics, but in most cases the syntax of a parameter is specific to + the implementation of the URI's dereferencing algorithm. + +3.4. Query + + The query component contains non-hierarchical data that, along with + data in the path component (Section 3.3), serves to identify a + resource within the scope of the URI's scheme and naming authority + (if any). The query component is indicated by the first question + mark ("?") character and terminated by a number sign ("#") character + or by the end of the URI. + + + +Berners-Lee, et al. Standards Track [Page 23] + +RFC 3986 URI Generic Syntax January 2005 + + + query = *( pchar / "/" / "?" ) + + The characters slash ("/") and question mark ("?") may represent data + within the query component. Beware that some older, erroneous + implementations may not handle such data correctly when it is used as + the base URI for relative references (Section 5.1), apparently + because they fail to distinguish query data from path data when + looking for hierarchical separators. However, as query components + are often used to carry identifying information in the form of + "key=value" pairs and one frequently used value is a reference to + another URI, it is sometimes better for usability to avoid percent- + encoding those characters. + +3.5. Fragment + + The fragment identifier component of a URI allows indirect + identification of a secondary resource by reference to a primary + resource and additional identifying information. The identified + secondary resource may be some portion or subset of the primary + resource, some view on representations of the primary resource, or + some other resource defined or described by those representations. A + fragment identifier component is indicated by the presence of a + number sign ("#") character and terminated by the end of the URI. + + fragment = *( pchar / "/" / "?" ) + + The semantics of a fragment identifier are defined by the set of + representations that might result from a retrieval action on the + primary resource. The fragment's format and resolution is therefore + dependent on the media type [RFC2046] of a potentially retrieved + representation, even though such a retrieval is only performed if the + URI is dereferenced. If no such representation exists, then the + semantics of the fragment are considered unknown and are effectively + unconstrained. Fragment identifier semantics are independent of the + URI scheme and thus cannot be redefined by scheme specifications. + + Individual media types may define their own restrictions on or + structures within the fragment identifier syntax for specifying + different types of subsets, views, or external references that are + identifiable as secondary resources by that media type. If the + primary resource has multiple representations, as is often the case + for resources whose representation is selected based on attributes of + the retrieval request (a.k.a., content negotiation), then whatever is + identified by the fragment should be consistent across all of those + representations. Each representation should either define the + fragment so that it corresponds to the same secondary resource, + regardless of how it is represented, or should leave the fragment + undefined (i.e., not found). + + + +Berners-Lee, et al. Standards Track [Page 24] + +RFC 3986 URI Generic Syntax January 2005 + + + As with any URI, use of a fragment identifier component does not + imply that a retrieval action will take place. A URI with a fragment + identifier may be used to refer to the secondary resource without any + implication that the primary resource is accessible or will ever be + accessed. + + Fragment identifiers have a special role in information retrieval + systems as the primary form of client-side indirect referencing, + allowing an author to specifically identify aspects of an existing + resource that are only indirectly provided by the resource owner. As + such, the fragment identifier is not used in the scheme-specific + processing of a URI; instead, the fragment identifier is separated + from the rest of the URI prior to a dereference, and thus the + identifying information within the fragment itself is dereferenced + solely by the user agent, regardless of the URI scheme. Although + this separate handling is often perceived to be a loss of + information, particularly for accurate redirection of references as + resources move over time, it also serves to prevent information + providers from denying reference authors the right to refer to + information within a resource selectively. Indirect referencing also + provides additional flexibility and extensibility to systems that use + URIs, as new media types are easier to define and deploy than new + schemes of identification. + + The characters slash ("/") and question mark ("?") are allowed to + represent data within the fragment identifier. Beware that some + older, erroneous implementations may not handle this data correctly + when it is used as the base URI for relative references (Section + 5.1). + +4. Usage + + When applications make reference to a URI, they do not always use the + full form of reference defined by the "URI" syntax rule. To save + space and take advantage of hierarchical locality, many Internet + protocol elements and media type formats allow an abbreviation of a + URI, whereas others restrict the syntax to a particular form of URI. + We define the most common forms of reference syntax in this + specification because they impact and depend upon the design of the + generic syntax, requiring a uniform parsing algorithm in order to be + interpreted consistently. + +4.1. URI Reference + + URI-reference is used to denote the most common usage of a resource + identifier. + + URI-reference = URI / relative-ref + + + +Berners-Lee, et al. Standards Track [Page 25] + +RFC 3986 URI Generic Syntax January 2005 + + + A URI-reference is either a URI or a relative reference. If the + URI-reference's prefix does not match the syntax of a scheme followed + by its colon separator, then the URI-reference is a relative + reference. + + A URI-reference is typically parsed first into the five URI + components, in order to determine what components are present and + whether the reference is relative. Then, each component is parsed + for its subparts and their validation. The ABNF of URI-reference, + along with the "first-match-wins" disambiguation rule, is sufficient + to define a validating parser for the generic syntax. Readers + familiar with regular expressions should see Appendix B for an + example of a non-validating URI-reference parser that will take any + given string and extract the URI components. + +4.2. Relative Reference + + A relative reference takes advantage of the hierarchical syntax + (Section 1.2.3) to express a URI reference relative to the name space + of another hierarchical URI. + + relative-ref = relative-part [ "?" query ] [ "#" fragment ] + + relative-part = "//" authority path-abempty + / path-absolute + / path-noscheme + / path-empty + + The URI referred to by a relative reference, also known as the target + URI, is obtained by applying the reference resolution algorithm of + Section 5. + + A relative reference that begins with two slash characters is termed + a network-path reference; such references are rarely used. A + relative reference that begins with a single slash character is + termed an absolute-path reference. A relative reference that does + not begin with a slash character is termed a relative-path reference. + + A path segment that contains a colon character (e.g., "this:that") + cannot be used as the first segment of a relative-path reference, as + it would be mistaken for a scheme name. Such a segment must be + preceded by a dot-segment (e.g., "./this:that") to make a relative- + path reference. + + + + + + + + +Berners-Lee, et al. Standards Track [Page 26] + +RFC 3986 URI Generic Syntax January 2005 + + +4.3. Absolute URI + + Some protocol elements allow only the absolute form of a URI without + a fragment identifier. For example, defining a base URI for later + use by relative references calls for an absolute-URI syntax rule that + does not allow a fragment. + + absolute-URI = scheme ":" hier-part [ "?" query ] + + URI scheme specifications must define their own syntax so that all + strings matching their scheme-specific syntax will also match the + grammar. Scheme specifications will not define + fragment identifier syntax or usage, regardless of its applicability + to resources identifiable via that scheme, as fragment identification + is orthogonal to scheme definition. However, scheme specifications + are encouraged to include a wide range of examples, including + examples that show use of the scheme's URIs with fragment identifiers + when such usage is appropriate. + +4.4. Same-Document Reference + + When a URI reference refers to a URI that is, aside from its fragment + component (if any), identical to the base URI (Section 5.1), that + reference is called a "same-document" reference. The most frequent + examples of same-document references are relative references that are + empty or include only the number sign ("#") separator followed by a + fragment identifier. + + When a same-document reference is dereferenced for a retrieval + action, the target of that reference is defined to be within the same + entity (representation, document, or message) as the reference; + therefore, a dereference should not result in a new retrieval action. + + Normalization of the base and target URIs prior to their comparison, + as described in Sections 6.2.2 and 6.2.3, is allowed but rarely + performed in practice. Normalization may increase the set of same- + document references, which may be of benefit to some caching + applications. As such, reference authors should not assume that a + slightly different, though equivalent, reference URI will (or will + not) be interpreted as a same-document reference by any given + application. + +4.5. Suffix Reference + + The URI syntax is designed for unambiguous reference to resources and + extensibility via the URI scheme. However, as URI identification and + usage have become commonplace, traditional media (television, radio, + newspapers, billboards, etc.) have increasingly used a suffix of the + + + +Berners-Lee, et al. Standards Track [Page 27] + +RFC 3986 URI Generic Syntax January 2005 + + + URI as a reference, consisting of only the authority and path + portions of the URI, such as + + www.w3.org/Addressing/ + + or simply a DNS registered name on its own. Such references are + primarily intended for human interpretation rather than for machines, + with the assumption that context-based heuristics are sufficient to + complete the URI (e.g., most registered names beginning with "www" + are likely to have a URI prefix of "http://"). Although there is no + standard set of heuristics for disambiguating a URI suffix, many + client implementations allow them to be entered by the user and + heuristically resolved. + + Although this practice of using suffix references is common, it + should be avoided whenever possible and should never be used in + situations where long-term references are expected. The heuristics + noted above will change over time, particularly when a new URI scheme + becomes popular, and are often incorrect when used out of context. + Furthermore, they can lead to security issues along the lines of + those described in [RFC1535]. + + As a URI suffix has the same syntax as a relative-path reference, a + suffix reference cannot be used in contexts where a relative + reference is expected. As a result, suffix references are limited to + places where there is no defined base URI, such as dialog boxes and + off-line advertisements. + +5. Reference Resolution + + This section defines the process of resolving a URI reference within + a context that allows relative references so that the result is a + string matching the syntax rule of Section 3. + +5.1. Establishing a Base URI + + The term "relative" implies that a "base URI" exists against which + the relative reference is applied. Aside from fragment-only + references (Section 4.4), relative references are only usable when a + base URI is known. A base URI must be established by the parser + prior to parsing URI references that might be relative. A base URI + must conform to the syntax rule (Section 4.3). If the + base URI is obtained from a URI reference, then that reference must + be converted to absolute form and stripped of any fragment component + prior to its use as a base URI. + + + + + + +Berners-Lee, et al. Standards Track [Page 28] + +RFC 3986 URI Generic Syntax January 2005 + + + The base URI of a reference can be established in one of four ways, + discussed below in order of precedence. The order of precedence can + be thought of in terms of layers, where the innermost defined base + URI has the highest precedence. This can be visualized graphically + as follows: + + .----------------------------------------------------------. + | .----------------------------------------------------. | + | | .----------------------------------------------. | | + | | | .----------------------------------------. | | | + | | | | .----------------------------------. | | | | + | | | | | | | | | | + | | | | `----------------------------------' | | | | + | | | | (5.1.1) Base URI embedded in content | | | | + | | | `----------------------------------------' | | | + | | | (5.1.2) Base URI of the encapsulating entity | | | + | | | (message, representation, or none) | | | + | | `----------------------------------------------' | | + | | (5.1.3) URI used to retrieve the entity | | + | `----------------------------------------------------' | + | (5.1.4) Default Base URI (application-dependent) | + `----------------------------------------------------------' + +5.1.1. Base URI Embedded in Content + + Within certain media types, a base URI for relative references can be + embedded within the content itself so that it can be readily obtained + by a parser. This can be useful for descriptive documents, such as + tables of contents, which may be transmitted to others through + protocols other than their usual retrieval context (e.g., email or + USENET news). + + It is beyond the scope of this specification to specify how, for each + media type, a base URI can be embedded. The appropriate syntax, when + available, is described by the data format specification associated + with each media type. + +5.1.2. Base URI from the Encapsulating Entity + + If no base URI is embedded, the base URI is defined by the + representation's retrieval context. For a document that is enclosed + within another entity, such as a message or archive, the retrieval + context is that entity. Thus, the default base URI of a + representation is the base URI of the entity in which the + representation is encapsulated. + + + + + + +Berners-Lee, et al. Standards Track [Page 29] + +RFC 3986 URI Generic Syntax January 2005 + + + A mechanism for embedding a base URI within MIME container types + (e.g., the message and multipart types) is defined by MHTML + [RFC2557]. Protocols that do not use the MIME message header syntax, + but that do allow some form of tagged metadata to be included within + messages, may define their own syntax for defining a base URI as part + of a message. + +5.1.3. Base URI from the Retrieval URI + + If no base URI is embedded and the representation is not encapsulated + within some other entity, then, if a URI was used to retrieve the + representation, that URI shall be considered the base URI. Note that + if the retrieval was the result of a redirected request, the last URI + used (i.e., the URI that resulted in the actual retrieval of the + representation) is the base URI. + +5.1.4. Default Base URI + + If none of the conditions described above apply, then the base URI is + defined by the context of the application. As this definition is + necessarily application-dependent, failing to define a base URI by + using one of the other methods may result in the same content being + interpreted differently by different types of applications. + + A sender of a representation containing relative references is + responsible for ensuring that a base URI for those references can be + established. Aside from fragment-only references, relative + references can only be used reliably in situations where the base URI + is well defined. + +5.2. Relative Resolution + + This section describes an algorithm for converting a URI reference + that might be relative to a given base URI into the parsed components + of the reference's target. The components can then be recomposed, as + described in Section 5.3, to form the target URI. This algorithm + provides definitive results that can be used to test the output of + other implementations. Applications may implement relative reference + resolution by using some other algorithm, provided that the results + match what would be given by this one. + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 30] + +RFC 3986 URI Generic Syntax January 2005 + + +5.2.1. Pre-parse the Base URI + + The base URI (Base) is established according to the procedure of + Section 5.1 and parsed into the five main components described in + Section 3. Note that only the scheme component is required to be + present in a base URI; the other components may be empty or + undefined. A component is undefined if its associated delimiter does + not appear in the URI reference; the path component is never + undefined, though it may be empty. + + Normalization of the base URI, as described in Sections 6.2.2 and + 6.2.3, is optional. A URI reference must be transformed to its + target URI before it can be normalized. + +5.2.2. Transform References + + For each URI reference (R), the following pseudocode describes an + algorithm for transforming R into its target URI (T): + + -- The URI reference is parsed into the five URI components + -- + (R.scheme, R.authority, R.path, R.query, R.fragment) = parse(R); + + -- A non-strict parser may ignore a scheme in the reference + -- if it is identical to the base URI's scheme. + -- + if ((not strict) and (R.scheme == Base.scheme)) then + undefine(R.scheme); + endif; + + + + + + + + + + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 31] + +RFC 3986 URI Generic Syntax January 2005 + + + if defined(R.scheme) then + T.scheme = R.scheme; + T.authority = R.authority; + T.path = remove_dot_segments(R.path); + T.query = R.query; + else + if defined(R.authority) then + T.authority = R.authority; + T.path = remove_dot_segments(R.path); + T.query = R.query; + else + if (R.path == "") then + T.path = Base.path; + if defined(R.query) then + T.query = R.query; + else + T.query = Base.query; + endif; + else + if (R.path starts-with "/") then + T.path = remove_dot_segments(R.path); + else + T.path = merge(Base.path, R.path); + T.path = remove_dot_segments(T.path); + endif; + T.query = R.query; + endif; + T.authority = Base.authority; + endif; + T.scheme = Base.scheme; + endif; + + T.fragment = R.fragment; + +5.2.3. Merge Paths + + The pseudocode above refers to a "merge" routine for merging a + relative-path reference with the path of the base URI. This is + accomplished as follows: + + o If the base URI has a defined authority component and an empty + path, then return a string consisting of "/" concatenated with the + reference's path; otherwise, + + + + + + + + +Berners-Lee, et al. Standards Track [Page 32] + +RFC 3986 URI Generic Syntax January 2005 + + + o return a string consisting of the reference's path component + appended to all but the last segment of the base URI's path (i.e., + excluding any characters after the right-most "/" in the base URI + path, or excluding the entire base URI path if it does not contain + any "/" characters). + +5.2.4. Remove Dot Segments + + The pseudocode also refers to a "remove_dot_segments" routine for + interpreting and removing the special "." and ".." complete path + segments from a referenced path. This is done after the path is + extracted from a reference, whether or not the path was relative, in + order to remove any invalid or extraneous dot-segments prior to + forming the target URI. Although there are many ways to accomplish + this removal process, we describe a simple method using two string + buffers. + + 1. The input buffer is initialized with the now-appended path + components and the output buffer is initialized to the empty + string. + + 2. While the input buffer is not empty, loop as follows: + + A. If the input buffer begins with a prefix of "../" or "./", + then remove that prefix from the input buffer; otherwise, + + B. if the input buffer begins with a prefix of "/./" or "/.", + where "." is a complete path segment, then replace that + prefix with "/" in the input buffer; otherwise, + + C. if the input buffer begins with a prefix of "/../" or "/..", + where ".." is a complete path segment, then replace that + prefix with "/" in the input buffer and remove the last + segment and its preceding "/" (if any) from the output + buffer; otherwise, + + D. if the input buffer consists only of "." or "..", then remove + that from the input buffer; otherwise, + + E. move the first path segment in the input buffer to the end of + the output buffer, including the initial "/" character (if + any) and any subsequent characters up to, but not including, + the next "/" character or the end of the input buffer. + + 3. Finally, the output buffer is returned as the result of + remove_dot_segments. + + + + + +Berners-Lee, et al. Standards Track [Page 33] + +RFC 3986 URI Generic Syntax January 2005 + + + Note that dot-segments are intended for use in URI references to + express an identifier relative to the hierarchy of names in the base + URI. The remove_dot_segments algorithm respects that hierarchy by + removing extra dot-segments rather than treat them as an error or + leaving them to be misinterpreted by dereference implementations. + + The following illustrates how the above steps are applied for two + examples of merged paths, showing the state of the two buffers after + each step. + + STEP OUTPUT BUFFER INPUT BUFFER + + 1 : /a/b/c/./../../g + 2E: /a /b/c/./../../g + 2E: /a/b /c/./../../g + 2E: /a/b/c /./../../g + 2B: /a/b/c /../../g + 2C: /a/b /../g + 2C: /a /g + 2E: /a/g + + STEP OUTPUT BUFFER INPUT BUFFER + + 1 : mid/content=5/../6 + 2E: mid /content=5/../6 + 2E: mid/content=5 /../6 + 2C: mid /6 + 2E: mid/6 + + Some applications may find it more efficient to implement the + remove_dot_segments algorithm by using two segment stacks rather than + strings. + + Note: Beware that some older, erroneous implementations will fail + to separate a reference's query component from its path component + prior to merging the base and reference paths, resulting in an + interoperability failure if the query component contains the + strings "/../" or "/./". + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 34] + +RFC 3986 URI Generic Syntax January 2005 + + +5.3. Component Recomposition + + Parsed URI components can be recomposed to obtain the corresponding + URI reference string. Using pseudocode, this would be: + + result = "" + + if defined(scheme) then + append scheme to result; + append ":" to result; + endif; + + if defined(authority) then + append "//" to result; + append authority to result; + endif; + + append path to result; + + if defined(query) then + append "?" to result; + append query to result; + endif; + + if defined(fragment) then + append "#" to result; + append fragment to result; + endif; + + return result; + + Note that we are careful to preserve the distinction between a + component that is undefined, meaning that its separator was not + present in the reference, and a component that is empty, meaning that + the separator was present and was immediately followed by the next + component separator or the end of the reference. + +5.4. Reference Resolution Examples + + Within a representation with a well defined base URI of + + http://a/b/c/d;p?q + + a relative reference is transformed to its target URI as follows. + + + + + + + +Berners-Lee, et al. Standards Track [Page 35] + +RFC 3986 URI Generic Syntax January 2005 + + +5.4.1. Normal Examples + + "g:h" = "g:h" + "g" = "http://a/b/c/g" + "./g" = "http://a/b/c/g" + "g/" = "http://a/b/c/g/" + "/g" = "http://a/g" + "//g" = "http://g" + "?y" = "http://a/b/c/d;p?y" + "g?y" = "http://a/b/c/g?y" + "#s" = "http://a/b/c/d;p?q#s" + "g#s" = "http://a/b/c/g#s" + "g?y#s" = "http://a/b/c/g?y#s" + ";x" = "http://a/b/c/;x" + "g;x" = "http://a/b/c/g;x" + "g;x?y#s" = "http://a/b/c/g;x?y#s" + "" = "http://a/b/c/d;p?q" + "." = "http://a/b/c/" + "./" = "http://a/b/c/" + ".." = "http://a/b/" + "../" = "http://a/b/" + "../g" = "http://a/b/g" + "../.." = "http://a/" + "../../" = "http://a/" + "../../g" = "http://a/g" + +5.4.2. Abnormal Examples + + Although the following abnormal examples are unlikely to occur in + normal practice, all URI parsers should be capable of resolving them + consistently. Each example uses the same base as that above. + + Parsers must be careful in handling cases where there are more ".." + segments in a relative-path reference than there are hierarchical + levels in the base URI's path. Note that the ".." syntax cannot be + used to change the authority component of a URI. + + "../../../g" = "http://a/g" + "../../../../g" = "http://a/g" + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 36] + +RFC 3986 URI Generic Syntax January 2005 + + + Similarly, parsers must remove the dot-segments "." and ".." when + they are complete components of a path, but not when they are only + part of a segment. + + "/./g" = "http://a/g" + "/../g" = "http://a/g" + "g." = "http://a/b/c/g." + ".g" = "http://a/b/c/.g" + "g.." = "http://a/b/c/g.." + "..g" = "http://a/b/c/..g" + + Less likely are cases where the relative reference uses unnecessary + or nonsensical forms of the "." and ".." complete path segments. + + "./../g" = "http://a/b/g" + "./g/." = "http://a/b/c/g/" + "g/./h" = "http://a/b/c/g/h" + "g/../h" = "http://a/b/c/h" + "g;x=1/./y" = "http://a/b/c/g;x=1/y" + "g;x=1/../y" = "http://a/b/c/y" + + Some applications fail to separate the reference's query and/or + fragment components from the path component before merging it with + the base path and removing dot-segments. This error is rarely + noticed, as typical usage of a fragment never includes the hierarchy + ("/") character and the query component is not normally used within + relative references. + + "g?y/./x" = "http://a/b/c/g?y/./x" + "g?y/../x" = "http://a/b/c/g?y/../x" + "g#s/./x" = "http://a/b/c/g#s/./x" + "g#s/../x" = "http://a/b/c/g#s/../x" + + Some parsers allow the scheme name to be present in a relative + reference if it is the same as the base URI scheme. This is + considered to be a loophole in prior specifications of partial URI + [RFC1630]. Its use should be avoided but is allowed for backward + compatibility. + + "http:g" = "http:g" ; for strict parsers + / "http://a/b/c/g" ; for backward compatibility + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 37] + +RFC 3986 URI Generic Syntax January 2005 + + +6. Normalization and Comparison + + One of the most common operations on URIs is simple comparison: + determining whether two URIs are equivalent without using the URIs to + access their respective resource(s). A comparison is performed every + time a response cache is accessed, a browser checks its history to + color a link, or an XML parser processes tags within a namespace. + Extensive normalization prior to comparison of URIs is often used by + spiders and indexing engines to prune a search space or to reduce + duplication of request actions and response storage. + + URI comparison is performed for some particular purpose. Protocols + or implementations that compare URIs for different purposes will + often be subject to differing design trade-offs in regards to how + much effort should be spent in reducing aliased identifiers. This + section describes various methods that may be used to compare URIs, + the trade-offs between them, and the types of applications that might + use them. + +6.1. Equivalence + + Because URIs exist to identify resources, presumably they should be + considered equivalent when they identify the same resource. However, + this definition of equivalence is not of much practical use, as there + is no way for an implementation to compare two resources unless it + has full knowledge or control of them. For this reason, + determination of equivalence or difference of URIs is based on string + comparison, perhaps augmented by reference to additional rules + provided by URI scheme definitions. We use the terms "different" and + "equivalent" to describe the possible outcomes of such comparisons, + but there are many application-dependent versions of equivalence. + + Even though it is possible to determine that two URIs are equivalent, + URI comparison is not sufficient to determine whether two URIs + identify different resources. For example, an owner of two different + domain names could decide to serve the same resource from both, + resulting in two different URIs. Therefore, comparison methods are + designed to minimize false negatives while strictly avoiding false + positives. + + In testing for equivalence, applications should not directly compare + relative references; the references should be converted to their + respective target URIs before comparison. When URIs are compared to + select (or avoid) a network action, such as retrieval of a + representation, fragment components (if any) should be excluded from + the comparison. + + + + + +Berners-Lee, et al. Standards Track [Page 38] + +RFC 3986 URI Generic Syntax January 2005 + + +6.2. Comparison Ladder + + A variety of methods are used in practice to test URI equivalence. + These methods fall into a range, distinguished by the amount of + processing required and the degree to which the probability of false + negatives is reduced. As noted above, false negatives cannot be + eliminated. In practice, their probability can be reduced, but this + reduction requires more processing and is not cost-effective for all + applications. + + If this range of comparison practices is considered as a ladder, the + following discussion will climb the ladder, starting with practices + that are cheap but have a relatively higher chance of producing false + negatives, and proceeding to those that have higher computational + cost and lower risk of false negatives. + +6.2.1. Simple String Comparison + + If two URIs, when considered as character strings, are identical, + then it is safe to conclude that they are equivalent. This type of + equivalence test has very low computational cost and is in wide use + in a variety of applications, particularly in the domain of parsing. + + Testing strings for equivalence requires some basic precautions. + This procedure is often referred to as "bit-for-bit" or + "byte-for-byte" comparison, which is potentially misleading. Testing + strings for equality is normally based on pair comparison of the + characters that make up the strings, starting from the first and + proceeding until both strings are exhausted and all characters are + found to be equal, until a pair of characters compares unequal, or + until one of the strings is exhausted before the other. + + This character comparison requires that each pair of characters be + put in comparable form. For example, should one URI be stored in a + byte array in EBCDIC encoding and the second in a Java String object + (UTF-16), bit-for-bit comparisons applied naively will produce + errors. It is better to speak of equality on a character-for- + character basis rather than on a byte-for-byte or bit-for-bit basis. + In practical terms, character-by-character comparisons should be done + codepoint-by-codepoint after conversion to a common character + encoding. + + False negatives are caused by the production and use of URI aliases. + Unnecessary aliases can be reduced, regardless of the comparison + method, by consistently providing URI references in an already- + normalized form (i.e., a form identical to what would be produced + after normalization is applied, as described below). + + + + +Berners-Lee, et al. Standards Track [Page 39] + +RFC 3986 URI Generic Syntax January 2005 + + + Protocols and data formats often limit some URI comparisons to simple + string comparison, based on the theory that people and + implementations will, in their own best interest, be consistent in + providing URI references, or at least consistent enough to negate any + efficiency that might be obtained from further normalization. + +6.2.2. Syntax-Based Normalization + + Implementations may use logic based on the definitions provided by + this specification to reduce the probability of false negatives. + This processing is moderately higher in cost than character-for- + character string comparison. For example, an application using this + approach could reasonably consider the following two URIs equivalent: + + example://a/b/c/%7Bfoo%7D + eXAMPLE://a/./b/../b/%63/%7bfoo%7d + + Web user agents, such as browsers, typically apply this type of URI + normalization when determining whether a cached response is + available. Syntax-based normalization includes such techniques as + case normalization, percent-encoding normalization, and removal of + dot-segments. + +6.2.2.1. Case Normalization + + For all URIs, the hexadecimal digits within a percent-encoding + triplet (e.g., "%3a" versus "%3A") are case-insensitive and therefore + should be normalized to use uppercase letters for the digits A-F. + + When a URI uses components of the generic syntax, the component + syntax equivalence rules always apply; namely, that the scheme and + host are case-insensitive and therefore should be normalized to + lowercase. For example, the URI is + equivalent to . The other generic syntax + components are assumed to be case-sensitive unless specifically + defined otherwise by the scheme (see Section 6.2.3). + +6.2.2.2. Percent-Encoding Normalization + + The percent-encoding mechanism (Section 2.1) is a frequent source of + variance among otherwise identical URIs. In addition to the case + normalization issue noted above, some URI producers percent-encode + octets that do not require percent-encoding, resulting in URIs that + are equivalent to their non-encoded counterparts. These URIs should + be normalized by decoding any percent-encoded octet that corresponds + to an unreserved character, as described in Section 2.3. + + + + + +Berners-Lee, et al. Standards Track [Page 40] + +RFC 3986 URI Generic Syntax January 2005 + + +6.2.2.3. Path Segment Normalization + + The complete path segments "." and ".." are intended only for use + within relative references (Section 4.1) and are removed as part of + the reference resolution process (Section 5.2). However, some + deployed implementations incorrectly assume that reference resolution + is not necessary when the reference is already a URI and thus fail to + remove dot-segments when they occur in non-relative paths. URI + normalizers should remove dot-segments by applying the + remove_dot_segments algorithm to the path, as described in + Section 5.2.4. + +6.2.3. Scheme-Based Normalization + + The syntax and semantics of URIs vary from scheme to scheme, as + described by the defining specification for each scheme. + Implementations may use scheme-specific rules, at further processing + cost, to reduce the probability of false negatives. For example, + because the "http" scheme makes use of an authority component, has a + default port of "80", and defines an empty path to be equivalent to + "/", the following four URIs are equivalent: + + http://example.com + http://example.com/ + http://example.com:/ + http://example.com:80/ + + In general, a URI that uses the generic syntax for authority with an + empty path should be normalized to a path of "/". Likewise, an + explicit ":port", for which the port is empty or the default for the + scheme, is equivalent to one where the port and its ":" delimiter are + elided and thus should be removed by scheme-based normalization. For + example, the second URI above is the normal form for the "http" + scheme. + + Another case where normalization varies by scheme is in the handling + of an empty authority component or empty host subcomponent. For many + scheme specifications, an empty authority or host is considered an + error; for others, it is considered equivalent to "localhost" or the + end-user's host. When a scheme defines a default for authority and a + URI reference to that default is desired, the reference should be + normalized to an empty authority for the sake of uniformity, brevity, + and internationalization. If, however, either the userinfo or port + subcomponents are non-empty, then the host should be given explicitly + even if it matches the default. + + Normalization should not remove delimiters when their associated + component is empty unless licensed to do so by the scheme + + + +Berners-Lee, et al. Standards Track [Page 41] + +RFC 3986 URI Generic Syntax January 2005 + + + specification. For example, the URI "http://example.com/?" cannot be + assumed to be equivalent to any of the examples above. Likewise, the + presence or absence of delimiters within a userinfo subcomponent is + usually significant to its interpretation. The fragment component is + not subject to any scheme-based normalization; thus, two URIs that + differ only by the suffix "#" are considered different regardless of + the scheme. + + Some schemes define additional subcomponents that consist of case- + insensitive data, giving an implicit license to normalizers to + convert this data to a common case (e.g., all lowercase). For + example, URI schemes that define a subcomponent of path to contain an + Internet hostname, such as the "mailto" URI scheme, cause that + subcomponent to be case-insensitive and thus subject to case + normalization (e.g., "mailto:Joe@Example.COM" is equivalent to + "mailto:Joe@example.com", even though the generic syntax considers + the path component to be case-sensitive). + + Other scheme-specific normalizations are possible. + +6.2.4. Protocol-Based Normalization + + Substantial effort to reduce the incidence of false negatives is + often cost-effective for web spiders. Therefore, they implement even + more aggressive techniques in URI comparison. For example, if they + observe that a URI such as + + http://example.com/data + + redirects to a URI differing only in the trailing slash + + http://example.com/data/ + + they will likely regard the two as equivalent in the future. This + kind of technique is only appropriate when equivalence is clearly + indicated by both the result of accessing the resources and the + common conventions of their scheme's dereference algorithm (in this + case, use of redirection by HTTP origin servers to avoid problems + with relative references). + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 42] + +RFC 3986 URI Generic Syntax January 2005 + + +7. Security Considerations + + A URI does not in itself pose a security threat. However, as URIs + are often used to provide a compact set of instructions for access to + network resources, care must be taken to properly interpret the data + within a URI, to prevent that data from causing unintended access, + and to avoid including data that should not be revealed in plain + text. + +7.1. Reliability and Consistency + + There is no guarantee that once a URI has been used to retrieve + information, the same information will be retrievable by that URI in + the future. Nor is there any guarantee that the information + retrievable via that URI in the future will be observably similar to + that retrieved in the past. The URI syntax does not constrain how a + given scheme or authority apportions its namespace or maintains it + over time. Such guarantees can only be obtained from the person(s) + controlling that namespace and the resource in question. A specific + URI scheme may define additional semantics, such as name persistence, + if those semantics are required of all naming authorities for that + scheme. + +7.2. Malicious Construction + + It is sometimes possible to construct a URI so that an attempt to + perform a seemingly harmless, idempotent operation, such as the + retrieval of a representation, will in fact cause a possibly damaging + remote operation. The unsafe URI is typically constructed by + specifying a port number other than that reserved for the network + protocol in question. The client unwittingly contacts a site running + a different protocol service, and data within the URI contains + instructions that, when interpreted according to this other protocol, + cause an unexpected operation. A frequent example of such abuse has + been the use of a protocol-based scheme with a port component of + "25", thereby fooling user agent software into sending an unintended + or impersonating message via an SMTP server. + + Applications should prevent dereference of a URI that specifies a TCP + port number within the "well-known port" range (0 - 1023) unless the + protocol being used to dereference that URI is compatible with the + protocol expected on that well-known port. Although IANA maintains a + registry of well-known ports, applications should make such + restrictions user-configurable to avoid preventing the deployment of + new services. + + + + + + +Berners-Lee, et al. Standards Track [Page 43] + +RFC 3986 URI Generic Syntax January 2005 + + + When a URI contains percent-encoded octets that match the delimiters + for a given resolution or dereference protocol (for example, CR and + LF characters for the TELNET protocol), these percent-encodings must + not be decoded before transmission across that protocol. Transfer of + the percent-encoding, which might violate the protocol, is less + harmful than allowing decoded octets to be interpreted as additional + operations or parameters, perhaps triggering an unexpected and + possibly harmful remote operation. + +7.3. Back-End Transcoding + + When a URI is dereferenced, the data within it is often parsed by + both the user agent and one or more servers. In HTTP, for example, a + typical user agent will parse a URI into its five major components, + access the authority's server, and send it the data within the + authority, path, and query components. A typical server will take + that information, parse the path into segments and the query into + key/value pairs, and then invoke implementation-specific handlers to + respond to the request. As a result, a common security concern for + server implementations that handle a URI, either as a whole or split + into separate components, is proper interpretation of the octet data + represented by the characters and percent-encodings within that URI. + + Percent-encoded octets must be decoded at some point during the + dereference process. Applications must split the URI into its + components and subcomponents prior to decoding the octets, as + otherwise the decoded octets might be mistaken for delimiters. + Security checks of the data within a URI should be applied after + decoding the octets. Note, however, that the "%00" percent-encoding + (NUL) may require special handling and should be rejected if the + application is not expecting to receive raw data within a component. + + Special care should be taken when the URI path interpretation process + involves the use of a back-end file system or related system + functions. File systems typically assign an operational meaning to + special characters, such as the "/", "\", ":", "[", and "]" + characters, and to special device names like ".", "..", "...", "aux", + "lpt", etc. In some cases, merely testing for the existence of such + a name will cause the operating system to pause or invoke unrelated + system calls, leading to significant security concerns regarding + denial of service and unintended data transfer. It would be + impossible for this specification to list all such significant + characters and device names. Implementers should research the + reserved names and characters for the types of storage device that + may be attached to their applications and restrict the use of data + obtained from URI components accordingly. + + + + + +Berners-Lee, et al. Standards Track [Page 44] + +RFC 3986 URI Generic Syntax January 2005 + + +7.4. Rare IP Address Formats + + Although the URI syntax for IPv4address only allows the common + dotted-decimal form of IPv4 address literal, many implementations + that process URIs make use of platform-dependent system routines, + such as gethostbyname() and inet_aton(), to translate the string + literal to an actual IP address. Unfortunately, such system routines + often allow and process a much larger set of formats than those + described in Section 3.2.2. + + For example, many implementations allow dotted forms of three + numbers, wherein the last part is interpreted as a 16-bit quantity + and placed in the right-most two bytes of the network address (e.g., + a Class B network). Likewise, a dotted form of two numbers means + that the last part is interpreted as a 24-bit quantity and placed in + the right-most three bytes of the network address (Class A), and a + single number (without dots) is interpreted as a 32-bit quantity and + stored directly in the network address. Adding further to the + confusion, some implementations allow each dotted part to be + interpreted as decimal, octal, or hexadecimal, as specified in the C + language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 + implies octal; otherwise, the number is interpreted as decimal). + + These additional IP address formats are not allowed in the URI syntax + due to differences between platform implementations. However, they + can become a security concern if an application attempts to filter + access to resources based on the IP address in string literal format. + If this filtering is performed, literals should be converted to + numeric form and filtered based on the numeric value, and not on a + prefix or suffix of the string form. + +7.5. Sensitive Information + + URI producers should not provide a URI that contains a username or + password that is intended to be secret. URIs are frequently + displayed by browsers, stored in clear text bookmarks, and logged by + user agent history and intermediary applications (proxies). A + password appearing within the userinfo component is deprecated and + should be considered an error (or simply ignored) except in those + rare cases where the 'password' parameter is intended to be public. + +7.6. Semantic Attacks + + Because the userinfo subcomponent is rarely used and appears before + the host in the authority component, it can be used to construct a + URI intended to mislead a human user by appearing to identify one + (trusted) naming authority while actually identifying a different + authority hidden behind the noise. For example + + + +Berners-Lee, et al. Standards Track [Page 45] + +RFC 3986 URI Generic Syntax January 2005 + + + ftp://cnn.example.com&story=breaking_news@10.0.0.1/top_story.htm + + might lead a human user to assume that the host is 'cnn.example.com', + whereas it is actually '10.0.0.1'. Note that a misleading userinfo + subcomponent could be much longer than the example above. + + A misleading URI, such as that above, is an attack on the user's + preconceived notions about the meaning of a URI rather than an attack + on the software itself. User agents may be able to reduce the impact + of such attacks by distinguishing the various components of the URI + when they are rendered, such as by using a different color or tone to + render userinfo if any is present, though there is no panacea. More + information on URI-based semantic attacks can be found in [Siedzik]. + +8. IANA Considerations + + URI scheme names, as defined by in Section 3.1, form a + registered namespace that is managed by IANA according to the + procedures defined in [BCP35]. No IANA actions are required by this + document. + +9. Acknowledgements + + This specification is derived from RFC 2396 [RFC2396], RFC 1808 + [RFC1808], and RFC 1738 [RFC1738]; the acknowledgements in those + documents still apply. It also incorporates the update (with + corrections) for IPv6 literals in the host syntax, as defined by + Robert M. Hinden, Brian E. Carpenter, and Larry Masinter in + [RFC2732]. In addition, contributions by Gisle Aas, Reese Anschultz, + Daniel Barclay, Tim Bray, Mike Brown, Rob Cameron, Jeremy Carroll, + Dan Connolly, Adam M. Costello, John Cowan, Jason Diamond, Martin + Duerst, Stefan Eissing, Clive D.W. Feather, Al Gilman, Tony Hammond, + Elliotte Harold, Pat Hayes, Henry Holtzman, Ian B. Jacobs, Michael + Kay, John C. Klensin, Graham Klyne, Dan Kohn, Bruce Lilly, Andrew + Main, Dave McAlpin, Ira McDonald, Michael Mealling, Ray Merkert, + Stephen Pollei, Julian Reschke, Tomas Rokicki, Miles Sabin, Kai + Schaetzl, Mark Thomson, Ronald Tschalaer, Norm Walsh, Marc Warne, + Stuart Williams, and Henry Zongaro are gratefully acknowledged. + +10. References + +10.1. Normative References + + [ASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + + + + + +Berners-Lee, et al. Standards Track [Page 46] + +RFC 3986 URI Generic Syntax January 2005 + + + [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [STD63] Yergeau, F., "UTF-8, a transformation format of + ISO 10646", STD 63, RFC 3629, November 2003. + + [UCS] International Organization for Standardization, + "Information Technology - Universal Multiple-Octet Coded + Character Set (UCS)", ISO/IEC 10646:2003, December 2003. + +10.2. Informative References + + [BCP19] Freed, N. and J. Postel, "IANA Charset Registration + Procedures", BCP 19, RFC 2978, October 2000. + + [BCP35] Petke, R. and I. King, "Registration Procedures for URL + Scheme Names", BCP 35, RFC 2717, November 1999. + + [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet + host table specification", RFC 952, October 1985. + + [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", + STD 13, RFC 1034, November 1987. + + [RFC1123] Braden, R., "Requirements for Internet Hosts - Application + and Support", STD 3, RFC 1123, October 1989. + + [RFC1535] Gavron, E., "A Security Problem and Proposed Correction + With Widely Deployed DNS Software", RFC 1535, + October 1993. + + [RFC1630] Berners-Lee, T., "Universal Resource Identifiers in WWW: A + Unifying Syntax for the Expression of Names and Addresses + of Objects on the Network as used in the World-Wide Web", + RFC 1630, June 1994. + + [RFC1736] Kunze, J., "Functional Recommendations for Internet + Resource Locators", RFC 1736, February 1995. + + [RFC1737] Sollins, K. and L. Masinter, "Functional Requirements for + Uniform Resource Names", RFC 1737, December 1994. + + [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [RFC1808] Fielding, R., "Relative Uniform Resource Locators", + RFC 1808, June 1995. + + + + +Berners-Lee, et al. Standards Track [Page 47] + +RFC 3986 URI Generic Syntax January 2005 + + + [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part Two: Media Types", RFC 2046, + November 1996. + + [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. + + [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifiers (URI): Generic Syntax", RFC 2396, + August 1998. + + [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. + Jensen, "HTTP Extensions for Distributed Authoring -- + WEBDAV", RFC 2518, February 1999. + + [RFC2557] Palme, J., Hopmann, A., and N. Shelness, "MIME + Encapsulation of Aggregate Documents, such as HTML + (MHTML)", RFC 2557, March 1999. + + [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke, + "Guidelines for new URL Schemes", RFC 2718, November 1999. + + [RFC2732] Hinden, R., Carpenter, B., and L. Masinter, "Format for + Literal IPv6 Addresses in URL's", RFC 2732, December 1999. + + [RFC3305] Mealling, M. and R. Denenberg, "Report from the Joint + W3C/IETF URI Planning Interest Group: Uniform Resource + Identifiers (URIs), URLs, and Uniform Resource Names + (URNs): Clarifications and Recommendations", RFC 3305, + August 2002. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003. + + [RFC3513] Hinden, R. and S. Deering, "Internet Protocol Version 6 + (IPv6) Addressing Architecture", RFC 3513, April 2003. + + [Siedzik] Siedzik, R., "Semantic Attacks: What's in a URL?", + April 2001, . + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 48] + +RFC 3986 URI Generic Syntax January 2005 + + +Appendix A. Collected ABNF for URI + + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty + + URI-reference = URI / relative-ref + + absolute-URI = scheme ":" hier-part [ "?" query ] + + relative-ref = relative-part [ "?" query ] [ "#" fragment ] + + relative-part = "//" authority path-abempty + / path-absolute + / path-noscheme + / path-empty + + scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) + + authority = [ userinfo "@" ] host [ ":" port ] + userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) + host = IP-literal / IPv4address / reg-name + port = *DIGIT + + IP-literal = "[" ( IPv6address / IPvFuture ) "]" + + IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) + + IPv6address = 6( h16 ":" ) ls32 + / "::" 5( h16 ":" ) ls32 + / [ h16 ] "::" 4( h16 ":" ) ls32 + / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 + / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 + / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 + / [ *4( h16 ":" ) h16 ] "::" ls32 + / [ *5( h16 ":" ) h16 ] "::" h16 + / [ *6( h16 ":" ) h16 ] "::" + + h16 = 1*4HEXDIG + ls32 = ( h16 ":" h16 ) / IPv4address + IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet + + + + + + + +Berners-Lee, et al. Standards Track [Page 49] + +RFC 3986 URI Generic Syntax January 2005 + + + dec-octet = DIGIT ; 0-9 + / %x31-39 DIGIT ; 10-99 + / "1" 2DIGIT ; 100-199 + / "2" %x30-34 DIGIT ; 200-249 + / "25" %x30-35 ; 250-255 + + reg-name = *( unreserved / pct-encoded / sub-delims ) + + path = path-abempty ; begins with "/" or is empty + / path-absolute ; begins with "/" but not "//" + / path-noscheme ; begins with a non-colon segment + / path-rootless ; begins with a segment + / path-empty ; zero characters + + path-abempty = *( "/" segment ) + path-absolute = "/" [ segment-nz *( "/" segment ) ] + path-noscheme = segment-nz-nc *( "/" segment ) + path-rootless = segment-nz *( "/" segment ) + path-empty = 0 + + segment = *pchar + segment-nz = 1*pchar + segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) + ; non-zero-length segment without any colon ":" + + pchar = unreserved / pct-encoded / sub-delims / ":" / "@" + + query = *( pchar / "/" / "?" ) + + fragment = *( pchar / "/" / "?" ) + + pct-encoded = "%" HEXDIG HEXDIG + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + reserved = gen-delims / sub-delims + gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + +Appendix B. Parsing a URI Reference with a Regular Expression + + As the "first-match-wins" algorithm is identical to the "greedy" + disambiguation method used by POSIX regular expressions, it is + natural and commonplace to use a regular expression for parsing the + potential five components of a URI reference. + + The following line is the regular expression for breaking-down a + well-formed URI reference into its components. + + + +Berners-Lee, et al. Standards Track [Page 50] + +RFC 3986 URI Generic Syntax January 2005 + + + ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))? + 12 3 4 5 6 7 8 9 + + The numbers in the second line above are only to assist readability; + they indicate the reference points for each subexpression (i.e., each + paired parenthesis). We refer to the value matched for subexpression + as $. For example, matching the above expression to + + http://www.ics.uci.edu/pub/ietf/uri/#Related + + results in the following subexpression matches: + + $1 = http: + $2 = http + $3 = //www.ics.uci.edu + $4 = www.ics.uci.edu + $5 = /pub/ietf/uri/ + $6 = + $7 = + $8 = #Related + $9 = Related + + where indicates that the component is not present, as is + the case for the query component in the above example. Therefore, we + can determine the value of the five components as + + scheme = $2 + authority = $4 + path = $5 + query = $7 + fragment = $9 + + Going in the opposite direction, we can recreate a URI reference from + its components by using the algorithm of Section 5.3. + +Appendix C. Delimiting a URI in Context + + URIs are often transmitted through formats that do not provide a + clear context for their interpretation. For example, there are many + occasions when a URI is included in plain text; examples include text + sent in email, USENET news, and on printed paper. In such cases, it + is important to be able to delimit the URI from the rest of the text, + and in particular from punctuation marks that might be mistaken for + part of the URI. + + In practice, URIs are delimited in a variety of ways, but usually + within double-quotes "http://example.com/", angle brackets + , or just by using whitespace: + + + +Berners-Lee, et al. Standards Track [Page 51] + +RFC 3986 URI Generic Syntax January 2005 + + + http://example.com/ + + These wrappers do not form part of the URI. + + In some cases, extra whitespace (spaces, line-breaks, tabs, etc.) may + have to be added to break a long URI across lines. The whitespace + should be ignored when the URI is extracted. + + No whitespace should be introduced after a hyphen ("-") character. + Because some typesetters and printers may (erroneously) introduce a + hyphen at the end of line when breaking it, the interpreter of a URI + containing a line break immediately after a hyphen should ignore all + whitespace around the line break and should be aware that the hyphen + may or may not actually be part of the URI. + + Using <> angle brackets around each URI is especially recommended as + a delimiting style for a reference that contains embedded whitespace. + + The prefix "URL:" (with or without a trailing space) was formerly + recommended as a way to help distinguish a URI from other bracketed + designators, though it is not commonly used in practice and is no + longer recommended. + + For robustness, software that accepts user-typed URI should attempt + to recognize and strip both delimiters and embedded whitespace. + + For example, the text + + Yes, Jim, I found it under "http://www.w3.org/Addressing/", + but you can probably pick it up from . Note the warning in . + + contains the URI references + + http://www.w3.org/Addressing/ + ftp://foo.example.com/rfc/ + http://www.ics.uci.edu/pub/ietf/uri/historical.html#WARNING + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 52] + +RFC 3986 URI Generic Syntax January 2005 + + +Appendix D. Changes from RFC 2396 + +D.1. Additions + + An ABNF rule for URI has been introduced to correspond to one common + usage of the term: an absolute URI with optional fragment. + + IPv6 (and later) literals have been added to the list of possible + identifiers for the host portion of an authority component, as + described by [RFC2732], with the addition of "[" and "]" to the + reserved set and a version flag to anticipate future versions of IP + literals. Square brackets are now specified as reserved within the + authority component and are not allowed outside their use as + delimiters for an IP literal within host. In order to make this + change without changing the technical definition of the path, query, + and fragment components, those rules were redefined to directly + specify the characters allowed. + + As [RFC2732] defers to [RFC3513] for definition of an IPv6 literal + address, which, unfortunately, lacks an ABNF description of + IPv6address, we created a new ABNF rule for IPv6address that matches + the text representations defined by Section 2.2 of [RFC3513]. + Likewise, the definition of IPv4address has been improved in order to + limit each decimal octet to the range 0-255. + + Section 6, on URI normalization and comparison, has been completely + rewritten and extended by using input from Tim Bray and discussion + within the W3C Technical Architecture Group. + +D.2. Modifications + + The ad-hoc BNF syntax of RFC 2396 has been replaced with the ABNF of + [RFC2234]. This change required all rule names that formerly + included underscore characters to be renamed with a dash instead. In + addition, a number of syntax rules have been eliminated or simplified + to make the overall grammar more comprehensible. Specifications that + refer to the obsolete grammar rules may be understood by replacing + those rules according to the following table: + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 53] + +RFC 3986 URI Generic Syntax January 2005 + + + +----------------+--------------------------------------------------+ + | obsolete rule | translation | + +----------------+--------------------------------------------------+ + | absoluteURI | absolute-URI | + | relativeURI | relative-part [ "?" query ] | + | hier_part | ( "//" authority path-abempty / | + | | path-absolute ) [ "?" query ] | + | | | + | opaque_part | path-rootless [ "?" query ] | + | net_path | "//" authority path-abempty | + | abs_path | path-absolute | + | rel_path | path-rootless | + | rel_segment | segment-nz-nc | + | reg_name | reg-name | + | server | authority | + | hostport | host [ ":" port ] | + | hostname | reg-name | + | path_segments | path-abempty | + | param | * | + | | | + | uric | unreserved / pct-encoded / ";" / "?" / ":" | + | | / "@" / "&" / "=" / "+" / "$" / "," / "/" | + | | | + | uric_no_slash | unreserved / pct-encoded / ";" / "?" / ":" | + | | / "@" / "&" / "=" / "+" / "$" / "," | + | | | + | mark | "-" / "_" / "." / "!" / "~" / "*" / "'" | + | | / "(" / ")" | + | | | + | escaped | pct-encoded | + | hex | HEXDIG | + | alphanum | ALPHA / DIGIT | + +----------------+--------------------------------------------------+ + + Use of the above obsolete rules for the definition of scheme-specific + syntax is deprecated. + + Section 2, on characters, has been rewritten to explain what + characters are reserved, when they are reserved, and why they are + reserved, even when they are not used as delimiters by the generic + syntax. The mark characters that are typically unsafe to decode, + including the exclamation mark ("!"), asterisk ("*"), single-quote + ("'"), and open and close parentheses ("(" and ")"), have been moved + to the reserved set in order to clarify the distinction between + reserved and unreserved and, hopefully, to answer the most common + question of scheme designers. Likewise, the section on + percent-encoded characters has been rewritten, and URI normalizers + are now given license to decode any percent-encoded octets + + + +Berners-Lee, et al. Standards Track [Page 54] + +RFC 3986 URI Generic Syntax January 2005 + + + corresponding to unreserved characters. In general, the terms + "escaped" and "unescaped" have been replaced with "percent-encoded" + and "decoded", respectively, to reduce confusion with other forms of + escape mechanisms. + + The ABNF for URI and URI-reference has been redesigned to make them + more friendly to LALR parsers and to reduce complexity. As a result, + the layout form of syntax description has been removed, along with + the uric, uric_no_slash, opaque_part, net_path, abs_path, rel_path, + path_segments, rel_segment, and mark rules. All references to + "opaque" URIs have been replaced with a better description of how the + path component may be opaque to hierarchy. The relativeURI rule has + been replaced with relative-ref to avoid unnecessary confusion over + whether they are a subset of URI. The ambiguity regarding the + parsing of URI-reference as a URI or a relative-ref with a colon in + the first segment has been eliminated through the use of five + separate path matching rules. + + The fragment identifier has been moved back into the section on + generic syntax components and within the URI and relative-ref rules, + though it remains excluded from absolute-URI. The number sign ("#") + character has been moved back to the reserved set as a result of + reintegrating the fragment syntax. + + The ABNF has been corrected to allow the path component to be empty. + This also allows an absolute-URI to consist of nothing after the + "scheme:", as is present in practice with the "dav:" namespace + [RFC2518] and with the "about:" scheme used internally by many WWW + browser implementations. The ambiguity regarding the boundary + between authority and path has been eliminated through the use of + five separate path matching rules. + + Registry-based naming authorities that use the generic syntax are now + defined within the host rule. This change allows current + implementations, where whatever name provided is simply fed to the + local name resolution mechanism, to be consistent with the + specification. It also removes the need to re-specify DNS name + formats here. Furthermore, it allows the host component to contain + percent-encoded octets, which is necessary to enable + internationalized domain names to be provided in URIs, processed in + their native character encodings at the application layers above URI + processing, and passed to an IDNA library as a registered name in the + UTF-8 character encoding. The server, hostport, hostname, + domainlabel, toplabel, and alphanum rules have been removed. + + The resolving relative references algorithm of [RFC2396] has been + rewritten with pseudocode for this revision to improve clarity and + fix the following issues: + + + +Berners-Lee, et al. Standards Track [Page 55] + +RFC 3986 URI Generic Syntax January 2005 + + + o [RFC2396] section 5.2, step 6a, failed to account for a base URI + with no path. + + o Restored the behavior of [RFC1808] where, if the reference + contains an empty path and a defined query component, the target + URI inherits the base URI's path component. + + o The determination of whether a URI reference is a same-document + reference has been decoupled from the URI parser, simplifying the + URI processing interface within applications in a way consistent + with the internal architecture of deployed URI processing + implementations. The determination is now based on comparison to + the base URI after transforming a reference to absolute form, + rather than on the format of the reference itself. This change + may result in more references being considered "same-document" + under this specification than there would be under the rules given + in RFC 2396, especially when normalization is used to reduce + aliases. However, it does not change the status of existing + same-document references. + + o Separated the path merge routine into two routines: merge, for + describing combination of the base URI path with a relative-path + reference, and remove_dot_segments, for describing how to remove + the special "." and ".." segments from a composed path. The + remove_dot_segments algorithm is now applied to all URI reference + paths in order to match common implementations and to improve the + normalization of URIs in practice. This change only impacts the + parsing of abnormal references and same-scheme references wherein + the base URI has a non-hierarchical path. + +Index + + A + ABNF 11 + absolute 27 + absolute-path 26 + absolute-URI 27 + access 9 + authority 17, 18 + + B + base URI 28 + + C + character encoding 4 + character 4 + characters 8, 11 + coded character set 4 + + + +Berners-Lee, et al. Standards Track [Page 56] + +RFC 3986 URI Generic Syntax January 2005 + + + D + dec-octet 20 + dereference 9 + dot-segments 23 + + F + fragment 16, 24 + + G + gen-delims 13 + generic syntax 6 + + H + h16 20 + hier-part 16 + hierarchical 10 + host 18 + + I + identifier 5 + IP-literal 19 + IPv4 20 + IPv4address 19, 20 + IPv6 19 + IPv6address 19, 20 + IPvFuture 19 + + L + locator 7 + ls32 20 + + M + merge 32 + + N + name 7 + network-path 26 + + P + path 16, 22, 26 + path-abempty 22 + path-absolute 22 + path-empty 22 + path-noscheme 22 + path-rootless 22 + path-abempty 16, 22, 26 + path-absolute 16, 22, 26 + path-empty 16, 22, 26 + + + +Berners-Lee, et al. Standards Track [Page 57] + +RFC 3986 URI Generic Syntax January 2005 + + + path-rootless 16, 22 + pchar 23 + pct-encoded 12 + percent-encoding 12 + port 22 + + Q + query 16, 23 + + R + reg-name 21 + registered name 20 + relative 10, 28 + relative-path 26 + relative-ref 26 + remove_dot_segments 33 + representation 9 + reserved 12 + resolution 9, 28 + resource 5 + retrieval 9 + + S + same-document 27 + sameness 9 + scheme 16, 17 + segment 22, 23 + segment-nz 23 + segment-nz-nc 23 + sub-delims 13 + suffix 27 + + T + transcription 8 + + U + uniform 4 + unreserved 13 + URI grammar + absolute-URI 27 + ALPHA 11 + authority 18 + CR 11 + dec-octet 20 + DIGIT 11 + DQUOTE 11 + fragment 24 + gen-delims 13 + + + +Berners-Lee, et al. Standards Track [Page 58] + +RFC 3986 URI Generic Syntax January 2005 + + + h16 20 + HEXDIG 11 + hier-part 16 + host 19 + IP-literal 19 + IPv4address 20 + IPv6address 20 + IPvFuture 19 + LF 11 + ls32 20 + OCTET 11 + path 22 + path-abempty 22 + path-absolute 22 + path-empty 22 + path-noscheme 22 + path-rootless 22 + pchar 23 + pct-encoded 12 + port 22 + query 24 + reg-name 21 + relative-ref 26 + reserved 13 + scheme 17 + segment 23 + segment-nz 23 + segment-nz-nc 23 + SP 11 + sub-delims 13 + unreserved 13 + URI 16 + URI-reference 25 + userinfo 18 + URI 16 + URI-reference 25 + URL 7 + URN 7 + userinfo 18 + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 59] + +RFC 3986 URI Generic Syntax January 2005 + + +Authors' Addresses + + Tim Berners-Lee + World Wide Web Consortium + Massachusetts Institute of Technology + 77 Massachusetts Avenue + Cambridge, MA 02139 + USA + + Phone: +1-617-253-5702 + Fax: +1-617-258-5999 + EMail: timbl@w3.org + URI: http://www.w3.org/People/Berners-Lee/ + + + Roy T. Fielding + Day Software + 5251 California Ave., Suite 110 + Irvine, CA 92617 + USA + + Phone: +1-949-679-2960 + Fax: +1-949-679-2972 + EMail: fielding@gbiv.com + URI: http://roy.gbiv.com/ + + + Larry Masinter + Adobe Systems Incorporated + 345 Park Ave + San Jose, CA 95110 + USA + + Phone: +1-408-536-3024 + EMail: LMM@acm.org + URI: http://larry.masinter.net/ + + + + + + + + + + + + + + + +Berners-Lee, et al. Standards Track [Page 60] + +RFC 3986 URI Generic Syntax January 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the IETF's procedures with respect to rights in IETF Documents can + be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Berners-Lee, et al. Standards Track [Page 61] + diff --git a/docs/standards/references/rfc3987.txt b/docs/standards/references/rfc3987.txt new file mode 100644 index 0000000..f0b1513 --- /dev/null +++ b/docs/standards/references/rfc3987.txt @@ -0,0 +1,2579 @@ + + + + + + +Network Working Group M. Duerst +Request for Comments: 3987 W3C +Category: Standards Track M. Suignard + Microsoft Corporation + January 2005 + + + Internationalized Resource Identifiers (IRIs) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + This document defines a new protocol element, the Internationalized + Resource Identifier (IRI), as a complement to the Uniform Resource + Identifier (URI). An IRI is a sequence of characters from the + Universal Character Set (Unicode/ISO 10646). A mapping from IRIs to + URIs is defined, which means that IRIs can be used instead of URIs, + where appropriate, to identify resources. + + The approach of defining a new protocol element was chosen instead of + extending or changing the definition of URIs. This was done in order + to allow a clear distinction and to avoid incompatibilities with + existing software. Guidelines are provided for the use and + deployment of IRIs in various protocols, formats, and software + components that currently deal with URIs. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Overview and Motivation . . . . . . . . . . . . . . . . 3 + 1.2. Applicability . . . . . . . . . . . . . . . . . . . . . 3 + 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . 4 + 1.4. Notation . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. IRI Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 2.1. Summary of IRI Syntax . . . . . . . . . . . . . . . . . 6 + 2.2. ABNF for IRI References and IRIs . . . . . . . . . . . . 7 + + + + +Duerst & Suignard Standards Track [Page 1] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + 3. Relationship between IRIs and URIs . . . . . . . . . . . . . . 10 + 3.1. Mapping of IRIs to URIs . . . . . . . . . . . . . . . . 10 + 3.2. Converting URIs to IRIs . . . . . . . . . . . . . . . . 14 + 3.2.1. Examples . . . . . . . . . . . . . . . . . . . . 15 + 4. Bidirectional IRIs for Right-to-Left Languages. . . . . . . . 16 + 4.1. Logical Storage and Visual Presentation . . . . . . . . 17 + 4.2. Bidi IRI Structure . . . . . . . . . . . . . . . . . . . 18 + 4.3. Input of Bidi IRIs . . . . . . . . . . . . . . . . . . . 19 + 4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 19 + 5. Normalization and Comparison . . . . . . . . . . . . . . . . . 21 + 5.1. Equivalence . . . . . . . . . . . . . . . . . . . . . . 22 + 5.2. Preparation for Comparison . . . . . . . . . . . . . . . 22 + 5.3. Comparison Ladder . . . . . . . . . . . . . . . . . . . 23 + 5.3.1. Simple String Comparison . . . . . . . . . . . . 23 + 5.3.2. Syntax-Based Normalization . . . . . . . . . . . 24 + 5.3.3. Scheme-Based Normalization . . . . . . . . . . . 27 + 5.3.4. Protocol-Based Normalization . . . . . . . . . . 28 + 6. Use of IRIs . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 6.1. Limitations on UCS Characters Allowed in IRIs . . . . . 29 + 6.2. Software Interfaces and Protocols . . . . . . . . . . . 29 + 6.3. Format of URIs and IRIs in Documents and Protocols . . . 30 + 6.4. Use of UTF-8 for Encoding Original Characters .. . . . . 30 + 6.5. Relative IRI References . . . . . . . . . . . . . . . . 32 + 7. URI/IRI Processing Guidelines (informative) . . . . . . . . . 32 + 7.1. URI/IRI Software Interfaces . . . . . . . . . . . . . . 32 + 7.2. URI/IRI Entry . . . . . . . . . . . . . . . . . . . . . 33 + 7.3. URI/IRI Transfer between Applications . . . . . . . . . 33 + 7.4. URI/IRI Generation . . . . . . . . . . . . . . . . . . . 34 + 7.5. URI/IRI Selection . . . . . . . . . . . . . . . . . . . 34 + 7.6. Display of URIs/IRIs . . . . . . . . . . . . . . . . . . 35 + 7.7. Interpretation of URIs and IRIs . . . . . . . . . . . . 36 + 7.8. Upgrading Strategy . . . . . . . . . . . . . . . . . . . 36 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 39 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 40 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 40 + 10.2. Informative References . . . . . . . . . . . . . . . . . 41 + A. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 44 + A.1. New Scheme(s) . . . . . . . . . . . . . . . . . . . . . 44 + A.2. Character Encodings Other Than UTF-8 . . . . . . . . . . 44 + A.3. New Encoding Convention . . . . . . . . . . . . . . . . 44 + A.4. Indicating Character Encodings in the URI/IRI . . . . . 45 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 + Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 46 + + + + + + + +Duerst & Suignard Standards Track [Page 2] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +1. Introduction + +1.1. Overview and Motivation + + A Uniform Resource Identifier (URI) is defined in [RFC3986] as a + sequence of characters chosen from a limited subset of the repertoire + of US-ASCII [ASCII] characters. + + The characters in URIs are frequently used for representing words of + natural languages. This usage has many advantages: Such URIs are + easier to memorize, easier to interpret, easier to transcribe, easier + to create, and easier to guess. For most languages other than + English, however, the natural script uses characters other than A - + Z. For many people, handling Latin characters is as difficult as + handling the characters of other scripts is for those who use only + the Latin alphabet. Many languages with non-Latin scripts are + transcribed with Latin letters. These transcriptions are now often + used in URIs, but they introduce additional ambiguities. + + The infrastructure for the appropriate handling of characters from + local scripts is now widely deployed in local versions of operating + system and application software. Software that can handle a wide + variety of scripts and languages at the same time is increasingly + common. Also, increasing numbers of protocols and formats can carry + a wide range of characters. + + This document defines a new protocol element called Internationalized + Resource Identifier (IRI) by extending the syntax of URIs to a much + wider repertoire of characters. It also defines "internationalized" + versions corresponding to other constructs from [RFC3986], such as + URI references. The syntax of IRIs is defined in section 2, and the + relationship between IRIs and URIs in section 3. + + Using characters outside of A - Z in IRIs brings some difficulties. + Section 4 discusses the special case of bidirectional IRIs, section 5 + various forms of equivalence between IRIs, and section 6 the use of + IRIs in different situations. Section 7 gives additional informative + guidelines, and section 8 security considerations. + +1.2. Applicability + + IRIs are designed to be compatible with recommendations for new URI + schemes [RFC2718]. The compatibility is provided by specifying a + well-defined and deterministic mapping from the IRI character + sequence to the functionally equivalent URI character sequence. + Practical use of IRIs (or IRI references) in place of URIs (or URI + references) depends on the following conditions being met: + + + + +Duerst & Suignard Standards Track [Page 3] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + a. A protocol or format element should be explicitly designated to + be able to carry IRIs. The intent is not to introduce IRIs into + contexts that are not defined to accept them. For example, XML + schema [XMLSchema] has an explicit type "anyURI" that includes + IRIs and IRI references. Therefore, IRIs and IRI references can + be in attributes and elements of type "anyURI". On the other + hand, in the HTTP protocol [RFC2616], the Request URI is defined + as a URI, which means that direct use of IRIs is not allowed in + HTTP requests. + + b. The protocol or format carrying the IRIs should have a mechanism + to represent the wide range of characters used in IRIs, either + natively or by some protocol- or format-specific escaping + mechanism (for example, numeric character references in [XML1]). + + c. The URI corresponding to the IRI in question has to encode + original characters into octets using UTF-8. For new URI + schemes, this is recommended in [RFC2718]. It can apply to a + whole scheme (e.g., IMAP URLs [RFC2192] and POP URLs [RFC2384], + or the URN syntax [RFC2141]). It can apply to a specific part of + a URI, such as the fragment identifier (e.g., [XPointer]). It + can apply to a specific URI or part(s) thereof. For details, + please see section 6.4. + +1.3. Definitions + + The following definitions are used in this document; they follow the + terms in [RFC2130], [RFC2277], and [ISO10646]. + + character: A member of a set of elements used for the organization, + control, or representation of data. For example, "LATIN CAPITAL + LETTER A" names a character. + + octet: An ordered sequence of eight bits considered as a unit. + + character repertoire: A set of characters (in the mathematical + sense). + + sequence of characters: A sequence of characters (one after another). + + sequence of octets: A sequence of octets (one after another). + + character encoding: A method of representing a sequence of characters + as a sequence of octets (maybe with variants). Also, a method of + (unambiguously) converting a sequence of octets into a sequence of + characters. + + + + + +Duerst & Suignard Standards Track [Page 4] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + charset: The name of a parameter or attribute used to identify a + character encoding. + + UCS: Universal Character Set. The coded character set defined by + ISO/IEC 10646 [ISO10646] and the Unicode Standard [UNIV4]. + + IRI reference: Denotes the common usage of an Internationalized + Resource Identifier. An IRI reference may be absolute or + relative. However, the "IRI" that results from such a reference + only includes absolute IRIs; any relative IRI references are + resolved to their absolute form. Note that in [RFC2396] URIs did + not include fragment identifiers, but in [RFC3986] fragment + identifiers are part of URIs. + + running text: Human text (paragraphs, sentences, phrases) with syntax + according to orthographic conventions of a natural language, as + opposed to syntax defined for ease of processing by machines + (e.g., markup, programming languages). + + protocol element: Any portion of a message that affects processing of + that message by the protocol in question. + + presentation element: A presentation form corresponding to a protocol + element; for example, using a wider range of characters. + + create (a URI or IRI): With respect to URIs and IRIs, the term is + used for the initial creation. This may be the initial creation + of a resource with a certain identifier, or the initial exposition + of a resource under a particular identifier. + + generate (a URI or IRI): With respect to URIs and IRIs, the term is + used when the IRI is generated by derivation from other + information. + +1.4. Notation + + RFCs and Internet Drafts currently do not allow any characters + outside the US-ASCII repertoire. Therefore, this document uses + various special notations to denote such characters in examples. + + In text, characters outside US-ASCII are sometimes referenced by + using a prefix of 'U+', followed by four to six hexadecimal digits. + + To represent characters outside US-ASCII in examples, this document + uses two notations: 'XML Notation' and 'Bidi Notation'. + + + + + + +Duerst & Suignard Standards Track [Page 5] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + XML Notation uses a leading '&#x', a trailing ';', and the + hexadecimal number of the character in the UCS in between. For + example, я stands for CYRILLIC CAPITAL LETTER YA. In this + notation, an actual '&' is denoted by '&'. + + Bidi Notation is used for bidirectional examples: Lowercase letters + stand for Latin letters or other letters that are written left to + right, whereas uppercase letters represent Arabic or Hebrew letters + that are written right to left. + + To denote actual octets in examples (as opposed to percent-encoded + octets), the two hex digits denoting the octet are enclosed in "<" + and ">". For example, the octet often denoted as 0xc9 is denoted + here as . + + In this document, the key words "MUST", "MUST NOT", "REQUIRED", + "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", + and "OPTIONAL" are to be interpreted as described in [RFC2119]. + +2. IRI Syntax + + This section defines the syntax of Internationalized Resource + Identifiers (IRIs). + + As with URIs, an IRI is defined as a sequence of characters, not as a + sequence of octets. This definition accommodates the fact that IRIs + may be written on paper or read over the radio as well as stored or + transmitted digitally. The same IRI may be represented as different + sequences of octets in different protocols or documents if these + protocols or documents use different character encodings (and/or + transfer encodings). Using the same character encoding as the + containing protocol or document ensures that the characters in the + IRI can be handled (e.g., searched, converted, displayed) in the same + way as the rest of the protocol or document. + +2.1. Summary of IRI Syntax + + IRIs are defined similarly to URIs in [RFC3986], but the class of + unreserved characters is extended by adding the characters of the UCS + (Universal Character Set, [ISO10646]) beyond U+007F, subject to the + limitations given in the syntax rules below and in section 6.1. + + Otherwise, the syntax and use of components and reserved characters + is the same as that in [RFC3986]. All the operations defined in + [RFC3986], such as the resolution of relative references, can be + applied to IRIs by IRI-processing software in exactly the same way as + they are for URIs by URI-processing software. + + + + +Duerst & Suignard Standards Track [Page 6] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + Characters outside the US-ASCII repertoire are not reserved and + therefore MUST NOT be used for syntactical purposes, such as to + delimit components in newly defined schemes. For example, U+00A2, + CENT SIGN, is not allowed as a delimiter in IRIs, because it is in + the 'iunreserved' category. This is similar to the fact that it is + not possible to use '-' as a delimiter in URIs, because it is in the + 'unreserved' category. + +2.2. ABNF for IRI References and IRIs + + Although it might be possible to define IRI references and IRIs + merely by their transformation to URI references and URIs, they can + also be accepted and processed directly. Therefore, an ABNF + definition for IRI references (which are the most general concept and + the start of the grammar) and IRIs is given here. The syntax of this + ABNF is described in [RFC2234]. Character numbers are taken from the + UCS, without implying any actual binary encoding. Terminals in the + ABNF are characters, not bytes. + + The following grammar closely follows the URI grammar in [RFC3986], + except that the range of unreserved characters is expanded to include + UCS characters, with the restriction that private UCS characters can + occur only in query parts. The grammar is split into two parts: + Rules that differ from [RFC3986] because of the above-mentioned + expansion, and rules that are the same as those in [RFC3986]. For + rules that are different than those in [RFC3986], the names of the + non-terminals have been changed as follows. If the non-terminal + contains 'URI', this has been changed to 'IRI'. Otherwise, an 'i' + has been prefixed. + + The following rules are different from those in [RFC3986]: + + IRI = scheme ":" ihier-part [ "?" iquery ] + [ "#" ifragment ] + + ihier-part = "//" iauthority ipath-abempty + / ipath-absolute + / ipath-rootless + / ipath-empty + + IRI-reference = IRI / irelative-ref + + absolute-IRI = scheme ":" ihier-part [ "?" iquery ] + + irelative-ref = irelative-part [ "?" iquery ] [ "#" ifragment ] + + irelative-part = "//" iauthority ipath-abempty + / ipath-absolute + + + +Duerst & Suignard Standards Track [Page 7] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + / ipath-noscheme + / ipath-empty + + iauthority = [ iuserinfo "@" ] ihost [ ":" port ] + iuserinfo = *( iunreserved / pct-encoded / sub-delims / ":" ) + ihost = IP-literal / IPv4address / ireg-name + + ireg-name = *( iunreserved / pct-encoded / sub-delims ) + + ipath = ipath-abempty ; begins with "/" or is empty + / ipath-absolute ; begins with "/" but not "//" + / ipath-noscheme ; begins with a non-colon segment + / ipath-rootless ; begins with a segment + / ipath-empty ; zero characters + + ipath-abempty = *( "/" isegment ) + ipath-absolute = "/" [ isegment-nz *( "/" isegment ) ] + ipath-noscheme = isegment-nz-nc *( "/" isegment ) + ipath-rootless = isegment-nz *( "/" isegment ) + ipath-empty = 0 + + isegment = *ipchar + isegment-nz = 1*ipchar + isegment-nz-nc = 1*( iunreserved / pct-encoded / sub-delims + / "@" ) + ; non-zero-length segment without any colon ":" + + ipchar = iunreserved / pct-encoded / sub-delims / ":" + / "@" + + iquery = *( ipchar / iprivate / "/" / "?" ) + + ifragment = *( ipchar / "/" / "?" ) + + iunreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" / ucschar + + ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF + / %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD + / %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD + / %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD + / %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD + / %xD0000-DFFFD / %xE1000-EFFFD + + iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD + + Some productions are ambiguous. The "first-match-wins" (a.k.a. + "greedy") algorithm applies. For details, see [RFC3986]. + + + + +Duerst & Suignard Standards Track [Page 8] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + The following rules are the same as those in [RFC3986]: + + scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) + + port = *DIGIT + + IP-literal = "[" ( IPv6address / IPvFuture ) "]" + + IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) + + IPv6address = 6( h16 ":" ) ls32 + / "::" 5( h16 ":" ) ls32 + / [ h16 ] "::" 4( h16 ":" ) ls32 + / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 + / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 + / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 + / [ *4( h16 ":" ) h16 ] "::" ls32 + / [ *5( h16 ":" ) h16 ] "::" h16 + / [ *6( h16 ":" ) h16 ] "::" + + h16 = 1*4HEXDIG + ls32 = ( h16 ":" h16 ) / IPv4address + + IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet + + dec-octet = DIGIT ; 0-9 + / %x31-39 DIGIT ; 10-99 + / "1" 2DIGIT ; 100-199 + / "2" %x30-34 DIGIT ; 200-249 + / "25" %x30-35 ; 250-255 + + pct-encoded = "%" HEXDIG HEXDIG + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + reserved = gen-delims / sub-delims + gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + + This syntax does not support IPv6 scoped addressing zone identifiers. + + + + + + + + + + + +Duerst & Suignard Standards Track [Page 9] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +3. Relationship between IRIs and URIs + + IRIs are meant to replace URIs in identifying resources for + protocols, formats, and software components that use a UCS-based + character repertoire. These protocols and components may never need + to use URIs directly, especially when the resource identifier is used + simply for identification purposes. However, when the resource + identifier is used for resource retrieval, it is in many cases + necessary to determine the associated URI, because currently most + retrieval mechanisms are only defined for URIs. In this case, IRIs + can serve as presentation elements for URI protocol elements. An + example would be an address bar in a Web user agent. (Additional + rationale is given in section 3.1.) + +3.1. Mapping of IRIs to URIs + + This section defines how to map an IRI to a URI. Everything in this + section also applies to IRI references and URI references, as well as + to components thereof (for example, fragment identifiers). + + This mapping has two purposes: + + Syntaxical. Many URI schemes and components define additional + syntactical restrictions not captured in section 2.2. + Scheme-specific restrictions are applied to IRIs by converting + IRIs to URIs and checking the URIs against the scheme-specific + restrictions. + + Interpretational. URIs identify resources in various ways. IRIs also + identify resources. When the IRI is used solely for + identification purposes, it is not necessary to map the IRI to a + URI (see section 5). However, when an IRI is used for resource + retrieval, the resource that the IRI locates is the same as the + one located by the URI obtained after converting the IRI according + to the procedure defined here. This means that there is no need + to define resolution separately on the IRI level. + + Applications MUST map IRIs to URIs by using the following two steps. + + Step 1. Generate a UCS character sequence from the original IRI + format. This step has the following three variants, + depending on the form of the input: + + a. If the IRI is written on paper, read aloud, or otherwise + represented as a sequence of characters independent of + any character encoding, represent the IRI as a sequence + of characters from the UCS normalized according to + Normalization Form C (NFC, [UTR15]). + + + +Duerst & Suignard Standards Track [Page 10] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + b. If the IRI is in some digital representation (e.g., an + octet stream) in some known non-Unicode character + encoding, convert the IRI to a sequence of characters + from the UCS normalized according to NFC. + + c. If the IRI is in a Unicode-based character encoding (for + example, UTF-8 or UTF-16), do not normalize (see section + 5.3.2.2 for details). Apply step 2 directly to the + encoded Unicode character sequence. + + Step 2. For each character in 'ucschar' or 'iprivate', apply steps + 2.1 through 2.3 below. + + 2.1. Convert the character to a sequence of one or more octets + using UTF-8 [RFC3629]. + + 2.2. Convert each octet to %HH, where HH is the hexadecimal + notation of the octet value. Note that this is identical + to the percent-encoding mechanism in section 2.1 of + [RFC3986]. To reduce variability, the hexadecimal notation + SHOULD use uppercase letters. + + 2.3. Replace the original character with the resulting character + sequence (i.e., a sequence of %HH triplets). + + The above mapping from IRIs to URIs produces URIs fully conforming to + [RFC3986]. The mapping is also an identity transformation for URIs + and is idempotent; applying the mapping a second time will not + change anything. Every URI is by definition an IRI. + + Systems accepting IRIs MAY convert the ireg-name component of an IRI + as follows (before step 2 above) for schemes known to use domain + names in ireg-name, if the scheme definition does not allow + percent-encoding for ireg-name: + + Replace the ireg-name part of the IRI by the part converted using the + ToASCII operation specified in section 4.1 of [RFC3490] on each + dot-separated label, and by using U+002E (FULL STOP) as a label + separator, with the flag UseSTD3ASCIIRules set to TRUE, and with the + flag AllowUnassigned set to FALSE for creating IRIs and set to TRUE + otherwise. + + + + + + + + + + +Duerst & Suignard Standards Track [Page 11] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + The ToASCII operation may fail, but this would mean that the IRI + cannot be resolved. This conversion SHOULD be used when the goal is + to maximize interoperability with legacy URI resolvers. For example, + the IRI + + "http://résumé.example.org" + + may be converted to + + "http://xn--rsum-bpad.example.org" + + instead of + + "http://r%C3%A9sum%C3%A9.example.org". + + An IRI with a scheme that is known to use domain names in ireg-name, + but where the scheme definition does not allow percent-encoding for + ireg-name, meets scheme-specific restrictions if either the + straightforward conversion or the conversion using the ToASCII + operation on ireg-name result in an URI that meets the scheme- + specific restrictions. + + Such an IRI resolves to the URI obtained after converting the IRI and + uses the ToASCII operation on ireg-name. Implementations do not have + to do this conversion as long as they produce the same result. + + Note: The difference between variants b and c in step 1 (using + normalization with NFC, versus not using any normalization) + accounts for the fact that in many non-Unicode character + encodings, some text cannot be represented directly. For example, + the word "Vietnam" is natively written "Việt Nam" + (containing a LATIN SMALL LETTER E WITH CIRCUMFLEX AND DOT BELOW) + in NFC, but a direct transcoding from the windows-1258 character + encoding leads to "Việt Nam" (containing a LATIN SMALL + LETTER E WITH CIRCUMFLEX followed by a COMBINING DOT BELOW). + Direct transcoding of other 8-bit encodings of Vietnamese may lead + to other representations. + + Note: The uniform treatment of the whole IRI in step 2 is important + to make processing independent of URI scheme. See [Gettys] for an + in-depth discussion. + + Note: In practice, whether the general mapping (steps 1 and 2) or the + ToASCII operation of [RFC3490] is used for ireg-name will not be + noticed if mapping from IRI to URI and resolution is tightly + integrated (e.g., carried out in the same user agent). But + + + + + +Duerst & Suignard Standards Track [Page 12] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + conversion using [RFC3490] may be able to better deal with + backwards compatibility issues in case mapping and resolution are + separated, as in the case of using an HTTP proxy. + + Note: Internationalized Domain Names may be contained in parts of an + IRI other than the ireg-name part. It is the responsibility of + scheme-specific implementations (if the Internationalized Domain + Name is part of the scheme syntax) or of server-side + implementations (if the Internationalized Domain Name is part of + 'iquery') to apply the necessary conversions at the appropriate + point. Example: Trying to validate the Web page at + http://résumé.example.org would lead to an IRI of + http://validator.w3.org/check?uri=http%3A%2F%2Frésumé. + example.org, which would convert to a URI of + http://validator.w3.org/check?uri=http%3A%2F%2Fr%C3%A9sum%C3%A9. + example.org. The server side implementation would be responsible + for making the necessary conversions to be able to retrieve the + Web page. + + Systems accepting IRIs MAY also deal with the printable characters in + US-ASCII that are not allowed in URIs, namely "<", ">", '"', space, + "{", "}", "|", "\", "^", and "`", in step 2 above. If these + characters are found but are not converted, then the conversion + SHOULD fail. Please note that the number sign ("#"), the percent + sign ("%"), and the square bracket characters ("[", "]") are not part + of the above list and MUST NOT be converted. Protocols and formats + that have used earlier definitions of IRIs including these characters + MAY require percent-encoding of these characters as a preprocessing + step to extract the actual IRI from a given field. This + preprocessing MAY also be used by applications allowing the user to + enter an IRI. + + Note: In this process (in step 2.3), characters allowed in URI + references and existing percent-encoded sequences are not encoded + further. (This mapping is similar to, but different from, the + encoding applied when arbitrary content is included in some part + of a URI.) For example, an IRI of + "http://www.example.org/red%09rosé#red" (in XML notation) is + converted to + "http://www.example.org/red%09ros%C3%A9#red", not to something + like + "http%3A%2F%2Fwww.example.org%2Fred%2509ros%C3%A9%23red". + + Note: Some older software transcoding to UTF-8 may produce illegal + output for some input, in particular for characters outside the + BMP (Basic Multilingual Plane). As an example, for the IRI with + non-BMP characters (in XML Notation): + "http://example.com/𐌀𐌁𐌂"; + + + +Duerst & Suignard Standards Track [Page 13] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + which contains the first three letters of the Old Italic alphabet, + the correct conversion to a URI is + "http://example.com/%F0%90%8C%80%F0%90%8C%81%F0%90%8C%82" + +3.2. Converting URIs to IRIs + + In some situations, converting a URI into an equivalent IRI may be + desirable. This section gives a procedure for this conversion. The + conversion described in this section will always result in an IRI + that maps back to the URI used as an input for the conversion (except + for potential case differences in percent-encoding and for potential + percent-encoded unreserved characters). However, the IRI resulting + from this conversion may not be exactly the same as the original IRI + (if there ever was one). + + URI-to-IRI conversion removes percent-encodings, but not all + percent-encodings can be eliminated. There are several reasons for + this: + + 1. Some percent-encodings are necessary to distinguish percent- + encoded and unencoded uses of reserved characters. + + 2. Some percent-encodings cannot be interpreted as sequences of + UTF-8 octets. + + (Note: The octet patterns of UTF-8 are highly regular. + Therefore, there is a very high probability, but no guarantee, + that percent-encodings that can be interpreted as sequences of + UTF-8 octets actually originated from UTF-8. For a detailed + discussion, see [Duerst97].) + + 3. The conversion may result in a character that is not appropriate + in an IRI. See sections 2.2, 4.1, and 6.1 for further details. + + Conversion from a URI to an IRI is done by using the following steps + (or any other algorithm that produces the same result): + + 1. Represent the URI as a sequence of octets in US-ASCII. + + 2. Convert all percent-encodings ("%" followed by two hexadecimal + digits) to the corresponding octets, except those corresponding + to "%", characters in "reserved", and characters in US-ASCII not + allowed in URIs. + + 3. Re-percent-encode any octet produced in step 2 that is not part + of a strictly legal UTF-8 octet sequence. + + + + + +Duerst & Suignard Standards Track [Page 14] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + 4. Re-percent-encode all octets produced in step 3 that in UTF-8 + represent characters that are not appropriate according to + sections 2.2, 4.1, and 6.1. + + 5. Interpret the resulting octet sequence as a sequence of characters + encoded in UTF-8. + + This procedure will convert as many percent-encoded characters as + possible to characters in an IRI. Because there are some choices + when step 4 is applied (see section 6.1), results may vary. + + Conversions from URIs to IRIs MUST NOT use any character encoding + other than UTF-8 in steps 3 and 4, even if it might be possible to + guess from the context that another character encoding than UTF-8 was + used in the URI. For example, the URI + "http://www.example.org/r%E9sum%E9.html" might with some guessing be + interpreted to contain two e-acute characters encoded as iso-8859-1. + It must not be converted to an IRI containing these e-acute + characters. Otherwise, in the future the IRI will be mapped to + "http://www.example.org/r%C3%A9sum%C3%A9.html", which is a different + URI from "http://www.example.org/r%E9sum%E9.html". + +3.2.1. Examples + + This section shows various examples of converting URIs to IRIs. Each + example shows the result after each of the steps 1 through 5 is + applied. XML Notation is used for the final result. Octets are + denoted by "<" followed by two hexadecimal digits followed by ">". + + The following example contains the sequence "%C3%BC", which is a + strictly legal UTF-8 sequence, and which is converted into the actual + character U+00FC, LATIN SMALL LETTER U WITH DIAERESIS (also known as + u-umlaut). + + 1. http://www.example.org/D%C3%BCrst + + 2. http://www.example.org/Drst + + 3. http://www.example.org/Drst + + 4. http://www.example.org/Drst + + 5. http://www.example.org/Dürst + + The following example contains the sequence "%FC", which might + represent U+00FC, LATIN SMALL LETTER U WITH DIAERESIS, in the + iso-8859-1 character encoding. (It might represent other characters + in other character encodings. For example, the octet in + + + +Duerst & Suignard Standards Track [Page 15] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + iso-8859-5 represents U+045C, CYRILLIC SMALL LETTER KJE.) Because + is not part of a strictly legal UTF-8 sequence, it is + re-percent-encoded in step 3. + + 1. http://www.example.org/D%FCrst + + 2. http://www.example.org/Drst + + 3. http://www.example.org/D%FCrst + + 4. http://www.example.org/D%FCrst + + 5. http://www.example.org/D%FCrst + + The following example contains "%e2%80%ae", which is the percent- + encoded UTF-8 character encoding of U+202E, RIGHT-TO-LEFT OVERRIDE. + Section 4.1 forbids the direct use of this character in an IRI. + Therefore, the corresponding octets are re-percent-encoded in step 4. + This example shows that the case (upper- or lowercase) of letters + used in percent-encodings may not be preserved. The example also + contains a punycode-encoded domain name label (xn--99zt52a), which is + not converted. + + 1. http://xn--99zt52a.example.org/%e2%80%ae + + 2. http://xn--99zt52a.example.org/<80> + + 3. http://xn--99zt52a.example.org/<80> + + 4. http://xn--99zt52a.example.org/%E2%80%AE + + 5. http://xn--99zt52a.example.org/%E2%80%AE + + Implementations with scheme-specific knowledge MAY convert + punycode-encoded domain name labels to the corresponding characters + by using the ToUnicode procedure. Thus, for the example above, the + label "xn--99zt52a" may be converted to U+7D0D U+8C46 (Japanese + Natto), leading to the overall IRI of + "http://納豆.example.org/%E2%80%AE". + +4. Bidirectional IRIs for Right-to-Left Languages + + Some UCS characters, such as those used in the Arabic and Hebrew + scripts, have an inherent right-to-left (rtl) writing direction. + IRIs containing these characters (called bidirectional IRIs or Bidi + IRIs) require additional attention because of the non-trivial + + + + + +Duerst & Suignard Standards Track [Page 16] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + relation between logical representation (used for digital + representation and for reading/spelling) and visual representation + (used for display/printing). + + Because of the complex interaction between the logical + representation, the visual representation, and the syntax of a Bidi + IRI, a balance is needed between various requirements. The main + requirements are + + 1. user-predictable conversion between visual and logical + representation; + + 2. the ability to include a wide range of characters in various + parts of the IRI; and + + 3. minor or no changes or restrictions for implementations. + +4.1. Logical Storage and Visual Presentation + + When stored or transmitted in digital representation, bidirectional + IRIs MUST be in full logical order and MUST conform to the IRI syntax + rules (which includes the rules relevant to their scheme). This + ensures that bidirectional IRIs can be processed in the same way as + other IRIs. + + Bidirectional IRIs MUST be rendered by using the Unicode + Bidirectional Algorithm [UNIV4], [UNI9]. Bidirectional IRIs MUST be + rendered in the same way as they would be if they were in a + left-to-right embedding; i.e., as if they were preceded by U+202A, + LEFT-TO-RIGHT EMBEDDING (LRE), and followed by U+202C, POP + DIRECTIONAL FORMATTING (PDF). Setting the embedding direction can + also be done in a higher-level protocol (e.g., the dir='ltr' + attribute in HTML). + + There is no requirement to use the above embedding if the display is + still the same without the embedding. For example, a bidirectional + IRI in a text with left-to-right base directionality (such as used + for English or Cyrillic) that is preceded and followed by whitespace + and strong left-to-right characters does not need an embedding. + Also, a bidirectional relative IRI reference that only contains + strong right-to-left characters and weak characters and that starts + and ends with a strong right-to-left character and appears in a text + with right-to-left base directionality (such as used for Arabic or + Hebrew) and is preceded and followed by whitespace and strong + characters does not need an embedding. + + + + + + +Duerst & Suignard Standards Track [Page 17] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + In some other cases, using U+200E, LEFT-TO-RIGHT MARK (LRM), may be + sufficient to force the correct display behavior. However, the + details of the Unicode Bidirectional algorithm are not always easy to + understand. Implementers are strongly advised to err on the side of + caution and to use embedding in all cases where they are not + completely sure that the display behavior is unaffected without the + embedding. + + The Unicode Bidirectional Algorithm ([UNI9], section 4.3) permits + higher-level protocols to influence bidirectional rendering. Such + changes by higher-level protocols MUST NOT be used if they change the + rendering of IRIs. + + The bidirectional formatting characters that may be used before or + after the IRI to ensure correct display are not themselves part of + the IRI. IRIs MUST NOT contain bidirectional formatting characters + (LRM, RLM, LRE, RLE, LRO, RLO, and PDF). They affect the visual + rendering of the IRI but do not appear themselves. It would + therefore not be possible to input an IRI with such characters + correctly. + +4.2. Bidi IRI Structure + + The Unicode Bidirectional Algorithm is designed mainly for running + text. To make sure that it does not affect the rendering of + bidirectional IRIs too much, some restrictions on bidirectional IRIs + are necessary. These restrictions are given in terms of delimiters + (structural characters, mostly punctuation such as "@", ".", ":", and + "/") and components (usually consisting mostly of letters and + digits). + + The following syntax rules from section 2.2 correspond to components + for the purpose of Bidi behavior: iuserinfo, ireg-name, isegment, + isegment-nz, isegment-nz-nc, ireg-name, iquery, and ifragment. + + Specifications that define the syntax of any of the above components + MAY divide them further and define smaller parts to be components + according to this document. As an example, the restrictions of + [RFC3490] on bidirectional domain names correspond to treating each + label of a domain name as a component for schemes with ireg-name as a + domain name. Even where the components are not defined formally, it + may be helpful to think about some syntax in terms of components and + to apply the relevant restrictions. For example, for the usual + name/value syntax in query parts, it is convenient to treat each name + and each value as a component. As another example, the extensions in + a resource name can be treated as separate components. + + + + + +Duerst & Suignard Standards Track [Page 18] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + For each component, the following restrictions apply: + + 1. A component SHOULD NOT use both right-to-left and left-to-right + characters. + + 2. A component using right-to-left characters SHOULD start and end + with right-to-left characters. + + The above restrictions are given as shoulds, rather than as musts. + For IRIs that are never presented visually, they are not relevant. + However, for IRIs in general, they are very important to ensure + consistent conversion between visual presentation and logical + representation, in both directions. + + Note: In some components, the above restrictions may actually be + strictly enforced. For example, [RFC3490] requires that these + restrictions apply to the labels of a host name for those schemes + where ireg-name is a host name. In some other components (for + example, path components) following these restrictions may not be + too difficult. For other components, such as parts of the query + part, it may be very difficult to enforce the restrictions because + the values of query parameters may be arbitrary character + sequences. + + If the above restrictions cannot be satisfied otherwise, the affected + component can always be mapped to URI notation as described in + section 3.1. Please note that the whole component has to be mapped + (see also Example 9 below). + +4.3. Input of Bidi IRIs + + Bidi input methods MUST generate Bidi IRIs in logical order while + rendering them according to section 4.1. During input, rendering + SHOULD be updated after every new character is input to avoid end- + user confusion. + +4.4. Examples + + This section gives examples of bidirectional IRIs, in Bidi Notation. + It shows legal IRIs with the relationship between logical and visual + representation and explains how certain phenomena in this + relationship may look strange to somebody not familiar with + bidirectional behavior, but familiar to users of Arabic and Hebrew. + It also shows what happens if the restrictions given in section 4.2 + are not followed. The examples below can be seen at [BidiEx], in + Arabic, Hebrew, and Bidi Notation variants. + + + + + +Duerst & Suignard Standards Track [Page 19] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + To read the bidi text in the examples, read the visual representation + from left to right until you encounter a block of rtl text. Read the + rtl block (including slashes and other special characters) from right + to left, then continue at the next unread ltr character. + + Example 1: A single component with rtl characters is inverted: + Logical representation: "http://ab.CDEFGH.ij/kl/mn/op.html" + Visual representation: "http://ab.HGFEDC.ij/kl/mn/op.html" + Components can be read one by one, and each component can be read in + its natural direction. + + Example 2: More than one consecutive component with rtl characters is + inverted as a whole: + Logical representation: "http://ab.CDE.FGH/ij/kl/mn/op.html" + Visual representation: "http://ab.HGF.EDC/ij/kl/mn/op.html" + A sequence of rtl components is read rtl, in the same way as a + sequence of rtl words is read rtl in a bidi text. + + Example 3: All components of an IRI (except for the scheme) are rtl. + All rtl components are inverted overall: + Logical representation: "http://AB.CD.EF/GH/IJ/KL?MN=OP;QR=ST#UV" + Visual representation: "http://VU#TS=RQ;PO=NM?LK/JI/HG/FE.DC.BA" + The whole IRI (except the scheme) is read rtl. Delimiters between + rtl components stay between the respective components; delimiters + between ltr and rtl components don't move. + + Example 4: Each of several sequences of rtl components is inverted on + its own: + Logical representation: "http://AB.CD.ef/gh/IJ/KL.html" + Visual representation: "http://DC.BA.ef/gh/LK/JI.html" + Each sequence of rtl components is read rtl, in the same way as each + sequence of rtl words in an ltr text is read rtl. + + Example 5: Example 2, applied to components of different kinds: + Logical representation: "http://ab.cd.EF/GH/ij/kl.html" + Visual representation: "http://ab.cd.HG/FE/ij/kl.html" + The inversion of the domain name label and the path component may be + unexpected, but it is consistent with other bidi behavior. For + reassurance that the domain component really is "ab.cd.EF", it may be + helpful to read aloud the visual representation following the bidi + algorithm. After "http://ab.cd." one reads the RTL block + "E-F-slash-G-H", which corresponds to the logical representation. + + Example 6: Same as Example 5, with more rtl components: + Logical representation: "http://ab.CD.EF/GH/IJ/kl.html" + Visual representation: "http://ab.JI/HG/FE.DC/kl.html" + The inversion of the domain name labels and the path components may + be easier to identify because the delimiters also move. + + + +Duerst & Suignard Standards Track [Page 20] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + Example 7: A single rtl component includes digits: + Logical representation: "http://ab.CDE123FGH.ij/kl/mn/op.html" + Visual representation: "http://ab.HGF123EDC.ij/kl/mn/op.html" + Numbers are written ltr in all cases but are treated as an additional + embedding inside a run of rtl characters. This is completely + consistent with usual bidirectional text. + + Example 8 (not allowed): Numbers are at the start or end of an rtl + component: + Logical representation: "http://ab.cd.ef/GH1/2IJ/KL.html" + Visual representation: "http://ab.cd.ef/LK/JI1/2HG.html" + The sequence "1/2" is interpreted by the bidi algorithm as a + fraction, fragmenting the components and leading to confusion. There + are other characters that are interpreted in a special way close to + numbers; in particular, "+", "-", "#", "$", "%", ",", ".", and ":". + + Example 9 (not allowed): The numbers in the previous example are + percent-encoded: + Logical representation: "http://ab.cd.ef/GH%31/%32IJ/KL.html", + Visual representation (Hebrew): "http://ab.cd.ef/%31HG/LK/JI%32.html" + Visual representation (Arabic): "http://ab.cd.ef/31%HG/%LK/JI32.html" + Depending on whether the uppercase letters represent Arabic or + Hebrew, the visual representation is different. + + Example 10 (allowed but not recommended): + Logical representation: "http://ab.CDEFGH.123/kl/mn/op.html" + Visual representation: "http://ab.123.HGFEDC/kl/mn/op.html" + Components consisting of only numbers are allowed (it would be rather + difficult to prohibit them), but these may interact with adjacent RTL + components in ways that are not easy to predict. + +5. Normalization and Comparison + + Note: The structure and much of the material for this section is + taken from section 6 of [RFC3986]; the differences are due to the + specifics of IRIs. + + One of the most common operations on IRIs is simple comparison: + Determining whether two IRIs are equivalent without using the IRIs or + the mapped URIs to access their respective resource(s). A comparison + is performed whenever a response cache is accessed, a browser checks + its history to color a link, or an XML parser processes tags within a + namespace. Extensive normalization prior to comparison of IRIs may + be used by spiders and indexing engines to prune a search space or + reduce duplication of request actions and response storage. + + + + + + +Duerst & Suignard Standards Track [Page 21] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + IRI comparison is performed for some particular purpose. Protocols + or implementations that compare IRIs for different purposes will + often be subject to differing design trade-offs in regards to how + much effort should be spent in reducing aliased identifiers. This + section describes various methods that may be used to compare IRIs, + the trade-offs between them, and the types of applications that might + use them. + +5.1. Equivalence + + Because IRIs exist to identify resources, presumably they should be + considered equivalent when they identify the same resource. However, + this definition of equivalence is not of much practical use, as there + is no way for an implementation to compare two resources unless it + has full knowledge or control of them. For this reason, determination + of equivalence or difference of IRIs is based on string comparison, + perhaps augmented by reference to additional rules provided by URI + scheme definitions. We use the terms "different" and "equivalent" to + describe the possible outcomes of such comparisons, but there are + many application-dependent versions of equivalence. + + Even though it is possible to determine that two IRIs are equivalent, + IRI comparison is not sufficient to determine whether two IRIs + identify different resources. For example, an owner of two different + domain names could decide to serve the same resource from both, + resulting in two different IRIs. Therefore, comparison methods are + designed to minimize false negatives while strictly avoiding false + positives. + + In testing for equivalence, applications should not directly compare + relative references; the references should be converted to their + respective target IRIs before comparison. When IRIs are compared to + select (or avoid) a network action, such as retrieval of a + representation, fragment components (if any) should be excluded from + the comparison. + + Applications using IRIs as identity tokens with no relationship to a + protocol MUST use the Simple String Comparison (see section 5.3.1). + All other applications MUST select one of the comparison practices + from the Comparison Ladder (see section 5.3 or, after IRI-to-URI + conversion, select one of the comparison practices from the URI + comparison ladder in [RFC3986], section 6.2) + +5.2. Preparation for Comparison + + Any kind of IRI comparison REQUIRES that all escapings or encodings + in the protocol or format that carries an IRI are resolved. This is + usually done when the protocol or format is parsed. Examples of such + + + +Duerst & Suignard Standards Track [Page 22] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + escapings or encodings are entities and numeric character references + in [HTML4] and [XML1]. As an example, + "http://example.org/rosé" (in HTML), + "http://example.org/rosé"; (in HTML or XML), and + "http://example.org/rosé"; (in HTML or XML) are all resolved into + what is denoted in this document (see section 1.4) as + "http://example.org/rosé"; (the "é" here standing for the + actual e-acute character, to compensate for the fact that this + document cannot contain non-ASCII characters). + + Similar considerations apply to encodings such as Transfer Codings in + HTTP (see [RFC2616]) and Content Transfer Encodings in MIME + ([RFC2045]), although in these cases, the encoding is based not on + characters but on octets, and additional care is required to make + sure that characters, and not just arbitrary octets, are compared + (see section 5.3.1). + +5.3. Comparison Ladder + + In practice, a variety of methods are used, to test IRI equivalence. + These methods fall into a range distinguished by the amount of + processing required and the degree to which the probability of false + negatives is reduced. As noted above, false negatives cannot be + eliminated. In practice, their probability can be reduced, but this + reduction requires more processing and is not cost-effective for all + applications. + + If this range of comparison practices is considered as a ladder, the + following discussion will climb the ladder, starting with practices + that are cheap but have a relatively higher chance of producing false + negatives, and proceeding to those that have higher computational + cost and lower risk of false negatives. + +5.3.1. Simple String Comparison + + If two IRIs, when considered as character strings, are identical, + then it is safe to conclude that they are equivalent. This type of + equivalence test has very low computational cost and is in wide use + in a variety of applications, particularly in the domain of parsing. + It is also used when a definitive answer to the question of IRI + equivalence is needed that is independent of the scheme used and that + can be calculated quickly and without accessing a network. An + example of such a case is XML Namespaces ([XMLNamespace]). + + Testing strings for equivalence requires some basic precautions. This + procedure is often referred to as "bit-for-bit" or "byte-for-byte" + comparison, which is potentially misleading. Testing strings for + equality is normally based on pair comparison of the characters that + + + +Duerst & Suignard Standards Track [Page 23] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + make up the strings, starting from the first and proceeding until + both strings are exhausted and all characters are found to be equal, + until a pair of characters compares unequal, or until one of the + strings is exhausted before the other. + + This character comparison requires that each pair of characters be + put in comparable encoding form. For example, should one IRI be + stored in a byte array in UTF-8 encoding form and the second in a + UTF-16 encoding form, bit-for-bit comparisons applied naively will + produce errors. It is better to speak of equality on a + character-for-character rather than on a byte-for-byte or bit-for-bit + basis. In practical terms, character-by-character comparisons should + be done codepoint by codepoint after conversion to a common character + encoding form. When comparing character by character, the comparison + function MUST NOT map IRIs to URIs, because such a mapping would + create additional spurious equivalences. It follows that an IRI + SHOULD NOT be modified when being transported if there is any chance + that this IRI might be used as an identifier. + + False negatives are caused by the production and use of IRI aliases. + Unnecessary aliases can be reduced, regardless of the comparison + method, by consistently providing IRI references in an already + normalized form (i.e., a form identical to what would be produced + after normalization is applied, as described below). Protocols and + data formats often limit some IRI comparisons to simple string + comparison, based on the theory that people and implementations will, + in their own best interest, be consistent in providing IRI + references, or at least be consistent enough to negate any efficiency + that might be obtained from further normalization. + +5.3.2. Syntax-Based Normalization + + Implementations may use logic based on the definitions provided by + this specification to reduce the probability of false negatives. This + processing is moderately higher in cost than character-for-character + string comparison. For example, an application using this approach + could reasonably consider the following two IRIs equivalent: + + example://a/b/c/%7Bfoo%7D/rosé + eXAMPLE://a/./b/../b/%63/%7bfoo%7d/ros%C3%A9 + + Web user agents, such as browsers, typically apply this type of IRI + normalization when determining whether a cached response is + available. Syntax-based normalization includes such techniques as + case normalization, character normalization, percent-encoding + normalization, and removal of dot-segments. + + + + + +Duerst & Suignard Standards Track [Page 24] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +5.3.2.1. Case Normalization + + For all IRIs, the hexadecimal digits within a percent-encoding + triplet (e.g., "%3a" versus "%3A") are case-insensitive and therefore + should be normalized to use uppercase letters for the digits A - F. + + When an IRI uses components of the generic syntax, the component + syntax equivalence rules always apply; namely, that the scheme and + US-ASCII only host are case insensitive and therefore should be + normalized to lowercase. For example, the URI + "HTTP://www.EXAMPLE.com/" is equivalent to "http://www.example.com/". + Case equivalence for non-ASCII characters in IRI components that are + IDNs are discussed in section 5.3.3. The other generic syntax + components are assumed to be case sensitive unless specifically + defined otherwise by the scheme. + + Creating schemes that allow case-insensitive syntax components + containing non-ASCII characters should be avoided. Case normalization + of non-ASCII characters can be culturally dependent and is always a + complex operation. The only exception concerns non-ASCII host names + for which the character normalization includes a mapping step derived + from case folding. + +5.3.2.2. Character Normalization + + The Unicode Standard [UNIV4] defines various equivalences between + sequences of characters for various purposes. Unicode Standard Annex + #15 [UTR15] defines various Normalization Forms for these + equivalences, in particular Normalization Form C (NFC, Canonical + Decomposition, followed by Canonical Composition) and Normalization + Form KC (NFKC, Compatibility Decomposition, followed by Canonical + Composition). + + Equivalence of IRIs MUST rely on the assumption that IRIs are + appropriately pre-character-normalized rather than apply character + normalization when comparing two IRIs. The exceptions are conversion + from a non-digital form, and conversion from a non-UCS-based + character encoding to a UCS-based character encoding. In these cases, + NFC or a normalizing transcoder using NFC MUST be used for + interoperability. To avoid false negatives and problems with + transcoding, IRIs SHOULD be created by using NFC. Using NFKC may + avoid even more problems; for example, by choosing half-width Latin + letters instead of full-width ones, and full-width instead of + half-width Katakana. + + As an example, "http://www.example.org/résumé.html" (in XML + Notation) is in NFC. On the other hand, + "http://www.example.org/résumé.html" is not in NFC. + + + +Duerst & Suignard Standards Track [Page 25] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + The former uses precombined e-acute characters, and the latter uses + "e" characters followed by combining acute accents. Both usages are + defined as canonically equivalent in [UNIV4]. + + Note: Because it is unknown how a particular sequence of characters + is being treated with respect to character normalization, it would + be inappropriate to allow third parties to normalize an IRI + arbitrarily. This does not contradict the recommendation that + when a resource is created, its IRI should be as character + normalized as possible (i.e., NFC or even NFKC). This is similar + to the uppercase/lowercase problems. Some parts of a URI are case + insensitive (domain name). For others, it is unclear whether they + are case sensitive, case insensitive, or something in between + (e.g., case sensitive, but with a multiple choice selection if the + wrong case is used, instead of a direct negative result). The + best recipe is that the creator use a reasonable capitalization + and, when transferring the URI, capitalization never be changed. + + Various IRI schemes may allow the usage of Internationalized Domain + Names (IDN) [RFC3490] either in the ireg-name part or elsewhere. + Character Normalization also applies to IDNs, as discussed in section + 5.3.3. + +5.3.2.3. Percent-Encoding Normalization + + The percent-encoding mechanism (section 2.1 of [RFC3986]) is a + frequent source of variance among otherwise identical IRIs. In + addition to the case normalization issue noted above, some IRI + producers percent-encode octets that do not require percent-encoding, + resulting in IRIs that are equivalent to their non encoded + counterparts. These IRIs should be normalized by decoding any + percent-encoded octet sequence that corresponds to an unreserved + character, as described in section 2.3 of [RFC3986]. + + For actual resolution, differences in percent-encoding (except for + the percent-encoding of reserved characters) MUST always result in + the same resource. For example, "http://example.org/~user", + "http://example.org/%7euser", and "http://example.org/%7Euser", must + resolve to the same resource. + + If this kind of equivalence is to be tested, the percent-encoding of + both IRIs to be compared has to be aligned; for example, by + converting both IRIs to URIs (see section 3.1), eliminating escape + differences in the resulting URIs, and making sure that the case of + the hexadecimal characters in the percent-encoding is always the same + (preferably uppercase). If the IRI is to be passed to another + + + + + +Duerst & Suignard Standards Track [Page 26] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + application or used further in some other way, its original form MUST + be preserved. The conversion described here should be performed only + for local comparison. + +5.3.2.4. Path Segment Normalization + + The complete path segments "." and ".." are intended only for use + within relative references (section 4.1 of [RFC3986]) and are removed + as part of the reference resolution process (section 5.2 of + [RFC3986]). However, some implementations may incorrectly assume + that reference resolution is not necessary when the reference is + already an IRI, and thus fail to remove dot-segments when they occur + in non-relative paths. IRI normalizers should remove dot-segments by + applying the remove_dot_segments algorithm to the path, as described + in section 5.2.4 of [RFC3986]. + +5.3.3. Scheme-Based Normalization + + The syntax and semantics of IRIs vary from scheme to scheme, as + described by the defining specification for each scheme. + Implementations may use scheme-specific rules, at further processing + cost, to reduce the probability of false negatives. For example, + because the "http" scheme makes use of an authority component, has a + default port of "80", and defines an empty path to be equivalent to + "/", the following four IRIs are equivalent: + + http://example.com + http://example.com/ + http://example.com:/ + http://example.com:80/ + + In general, an IRI that uses the generic syntax for authority with an + empty path should be normalized to a path of "/". Likewise, an + explicit ":port", for which the port is empty or the default for the + scheme, is equivalent to one where the port and its ":" delimiter are + elided and thus should be removed by scheme-based normalization. For + example, the second IRI above is the normal form for the "http" + scheme. + + Another case where normalization varies by scheme is in the handling + of an empty authority component or empty host subcomponent. For many + scheme specifications, an empty authority or host is considered an + error; for others, it is considered equivalent to "localhost" or the + end-user's host. When a scheme defines a default for authority and + an IRI reference to that default is desired, the reference should be + normalized to an empty authority for the sake of uniformity, brevity, + + + + + +Duerst & Suignard Standards Track [Page 27] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + and internationalization. If, however, either the userinfo or port + subcomponents are non-empty, then the host should be given explicitly + even if it matches the default. + + Normalization should not remove delimiters when their associated + component is empty unless it is licensed to do so by the scheme + specification. For example, the IRI "http://example.com/?" cannot be + assumed to be equivalent to any of the examples above. Likewise, the + presence or absence of delimiters within a userinfo subcomponent is + usually significant to its interpretation. The fragment component is + not subject to any scheme-based normalization; thus, two IRIs that + differ only by the suffix "#" are considered different regardless of + the scheme. + + Some IRI schemes may allow the usage of Internationalized Domain + Names (IDN) [RFC3490] either in their ireg-name part or elsewhere. + When in use in IRIs, those names SHOULD be validated by using the + ToASCII operation defined in [RFC3490], with the flags + "UseSTD3ASCIIRules" and "AllowUnassigned". An IRI containing an + invalid IDN cannot successfully be resolved. Validated IDN + components of IRIs SHOULD be character normalized by using the + Nameprep process [RFC3491]; however, for legibility purposes, they + SHOULD NOT be converted into ASCII Compatible Encoding (ACE). + + Scheme-based normalization may also consider IDN components and their + conversions to punycode as equivalent. As an example, + "http://résumé.example.org" may be considered equivalent to + "http://xn--rsum-bpad.example.org". + + Other scheme-specific normalizations are possible. + +5.3.4. Protocol-Based Normalization + + Substantial effort to reduce the incidence of false negatives is + often cost-effective for web spiders. Consequently, they implement + even more aggressive techniques in IRI comparison. For example, if + they observe that an IRI such as + + http://example.com/data + + redirects to an IRI differing only in the trailing slash + + http://example.com/data/ + + they will likely regard the two as equivalent in the future. This + kind of technique is only appropriate when equivalence is clearly + indicated by both the result of accessing the resources and the + + + + +Duerst & Suignard Standards Track [Page 28] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + common conventions of their scheme's dereference algorithm (in this + case, use of redirection by HTTP origin servers to avoid problems + with relative references). + +6. Use of IRIs + +6.1. Limitations on UCS Characters Allowed in IRIs + + This section discusses limitations on characters and character + sequences usable for IRIs beyond those given in section 2.2 and + section 4.1. The considerations in this section are relevant when + IRIs are created and when URIs are converted to IRIs. + + a. The repertoire of characters allowed in each IRI component is + limited by the definition of that component. For example, the + definition of the scheme component does not allow characters + beyond US-ASCII. + + (Note: In accordance with URI practice, generic IRI software + cannot and should not check for such limitations.) + + b. The UCS contains many areas of characters for which there are + strong visual look-alikes. Because of the likelihood of + transcription errors, these also should be avoided. This + includes the full-width equivalents of Latin characters, + half-width Katakana characters for Japanese, and many others. It + also includes many look-alikes of "space", "delims", and + "unwise", characters excluded in [RFC3491]. + + Additional information is available from [UNIXML]. [UNIXML] is + written in the context of running text rather than in that of + identifiers. Nevertheless, it discusses many of the categories of + characters not appropriate for IRIs. + +6.2. Software Interfaces and Protocols + + Although an IRI is defined as a sequence of characters, software + interfaces for URIs typically function on sequences of octets or + other kinds of code units. Thus, software interfaces and protocols + MUST define which character encoding is used. + + Intermediate software interfaces between IRI-capable components and + URI-only components MUST map the IRIs per section 3.1, when + transferring from IRI-capable to URI-only components. This mapping + SHOULD be applied as late as possible. It SHOULD NOT be applied + between components that are known to be able to handle IRIs. + + + + + +Duerst & Suignard Standards Track [Page 29] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +6.3. Format of URIs and IRIs in Documents and Protocols + + Document formats that transport URIs may have to be upgraded to allow + the transport of IRIs. In cases where the document as a whole has a + native character encoding, IRIs MUST also be encoded in this + character encoding and converted accordingly by a parser or + interpreter. IRI characters not expressible in the native character + encoding SHOULD be escaped by using the escaping conventions of the + document format if such conventions are available. Alternatively, + they MAY be percent-encoded according to section 3.1. For example, in + HTML or XML, numeric character references SHOULD be used. If a + document as a whole has a native character encoding and that + character encoding is not UTF-8, then IRIs MUST NOT be placed into + the document in the UTF-8 character encoding. + + Note: Some formats already accommodate IRIs, although they use + different terminology. HTML 4.0 [HTML4] defines the conversion from + IRIs to URIs as error-avoiding behavior. XML 1.0 [XML1], XLink + [XLink], XML Schema [XMLSchema], and specifications based upon them + allow IRIs. Also, it is expected that all relevant new W3C formats + and protocols will be required to handle IRIs [CharMod]. + +6.4. Use of UTF-8 for Encoding Original Characters + + This section discusses details and gives examples for point c) in + section 1.2. To be able to use IRIs, the URI corresponding to the + IRI in question has to encode original characters into octets by + using UTF-8. This can be specified for all URIs of a URI scheme or + can apply to individual URIs for schemes that do not specify how to + encode original characters. It can apply to the whole URI, or only + to some part. For background information on encoding characters into + URIs, see also section 2.5 of [RFC3986]. + + For new URI schemes, using UTF-8 is recommended in [RFC2718]. + Examples where UTF-8 is already used are the URN syntax [RFC2141], + IMAP URLs [RFC2192], and POP URLs [RFC2384]. On the other hand, + because the HTTP URL scheme does not specify how to encode original + characters, only some HTTP URLs can have corresponding but different + IRIs. + + For example, for a document with a URI of + "http://www.example.org/r%C3%A9sum%C3%A9.html", it is possible to + construct a corresponding IRI (in XML notation, see, section 1.4): + "http://www.example.org/résumé.html" ("é"; stands for + the e-acute character, and "%C3%A9" is the UTF-8 encoded and + percent-encoded representation of that character). On the other + hand, for a document with a URI of + + + + +Duerst & Suignard Standards Track [Page 30] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + "http://www.example.org/r%E9sum%E9.html", the percent-encoding octets + cannot be converted to actual characters in an IRI, as the + percent-encoding is not based on UTF-8. + + This means that for most URI schemes, there is no need to upgrade + their scheme definition in order for them to work with IRIs. The + main case where upgrading makes sense is when a scheme definition, or + a particular component of a scheme, is strictly limited to the use of + US-ASCII characters with no provision to include non-ASCII + characters/octets via percent-encoding, or if a scheme definition + currently uses highly scheme-specific provisions for the encoding of + non-ASCII characters. An example of this is the mailto: scheme + [RFC2368]. + + This specification does not upgrade any scheme specifications in any + way; this has to be done separately. Also, note that there is no + such thing as an "IRI scheme"; all IRIs use URI schemes, and all URI + schemes can be used with IRIs, even though in some cases only by + using URIs directly as IRIs, without any conversion. + + URI schemes can impose restrictions on the syntax of scheme-specific + URIs; i.e., URIs that are admissible under the generic URI syntax + [RFC3986] may not be admissible due to narrower syntactic constraints + imposed by a URI scheme specification. URI scheme definitions cannot + broaden the syntactic restrictions of the generic URI syntax; + otherwise, it would be possible to generate URIs that satisfied the + scheme-specific syntactic constraints without satisfying the + syntactic constraints of the generic URI syntax. However, additional + syntactic constraints imposed by URI scheme specifications are + applicable to IRI, as the corresponding URI resulting from the + mapping defined in section 3.1 MUST be a valid URI under the + syntactic restrictions of generic URI syntax and any narrower + restrictions imposed by the corresponding URI scheme specification. + + The requirement for the use of UTF-8 applies to all parts of a URI + (with the potential exception of the ireg-name part; see section + 3.1). However, it is possible that the capability of IRIs to + represent a wide range of characters directly is used just in some + parts of the IRI (or IRI reference). The other parts of the IRI may + only contain US-ASCII characters, or they may not be based on UTF-8. + They may be based on another character encoding, or they may directly + encode raw binary data (see also [RFC2397]). + + For example, it is possible to have a URI reference of + "http://www.example.org/r%E9sum%E9.xml#r%C3%A9sum%C3%A9", where the + document name is encoded in iso-8859-1 based on server settings, but + where the fragment identifier is encoded in UTF-8 according to + + + + +Duerst & Suignard Standards Track [Page 31] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + [XPointer]. The IRI corresponding to the above URI would be (in XML + notation) + "http://www.example.org/r%E9sum%E9.xml#résumé";. + + Similar considerations apply to query parts. The functionality of + IRIs (namely, to be able to include non-ASCII characters) can only be + used if the query part is encoded in UTF-8. + +6.5. Relative IRI References + + Processing of relative IRI references against a base is handled + straightforwardly; the algorithms of [RFC3986] can be applied + directly, treating the characters additionally allowed in IRI + references in the same way that unreserved characters are in URI + references. + +7. URI/IRI Processing Guidelines (Informative) + + This informative section provides guidelines for supporting IRIs in + the same software components and operations that currently process + URIs: Software interfaces that handle URIs, software that allows + users to enter URIs, software that creates or generates URIs, + software that displays URIs, formats and protocols that transport + URIs, and software that interprets URIs. These may all require + modification before functioning properly with IRIs. The + considerations in this section also apply to URI references and IRI + references. + +7.1. URI/IRI Software Interfaces + + Software interfaces that handle URIs, such as URI-handling APIs and + protocols transferring URIs, need interfaces and protocol elements + that are designed to carry IRIs. + + In case the current handling in an API or protocol is based on + US-ASCII, UTF-8 is recommended as the character encoding for IRIs, as + it is compatible with US-ASCII, is in accordance with the + recommendations of [RFC2277], and makes converting to URIs easy. In + any case, the API or protocol definition must clearly define the + character encoding to be used. + + The transfer from URI-only to IRI-capable components requires no + mapping, although the conversion described in section 3.2 above may + be performed. It is preferable not to perform this inverse + conversion when there is a chance that this cannot be done correctly. + + + + + + +Duerst & Suignard Standards Track [Page 32] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +7.2. URI/IRI Entry + + Some components allow users to enter URIs into the system by typing + or dictation, for example. This software must be updated to allow + for IRI entry. + + A person viewing a visual representation of an IRI (as a sequence of + glyphs, in some order, in some visual display) or hearing an IRI will + use an entry method for characters in the user's language to input + the IRI. Depending on the script and the input method used, this may + be a more or less complicated process. + + The process of IRI entry must ensure, as much as possible, that the + restrictions defined in section 2.2 are met. This may be done by + choosing appropriate input methods or variants/settings thereof, by + appropriately converting the characters being input, by eliminating + characters that cannot be converted, and/or by issuing a warning or + error message to the user. + + As an example of variant settings, input method editors for East + Asian Languages usually allow the input of Latin letters and related + characters in full-width or half-width versions. For IRI input, the + input method editor should be set so that it produces half-width + Latin letters and punctuation and full-width Katakana. + + An input field primarily or solely used for the input of URIs/IRIs + may allow the user to view an IRI as it is mapped to a URI. Places + where the input of IRIs is frequent may provide the possibility for + viewing an IRI as mapped to a URI. This will help users when some of + the software they use does not yet accept IRIs. + + An IRI input component interfacing to components that handle URIs, + but not IRIs, must map the IRI to a URI before passing it to these + components. + + For the input of IRIs with right-to-left characters, please see + section 4.3. + +7.3. URI/IRI Transfer between Applications + + Many applications, particularly mail user agents, try to detect URIs + appearing in plain text. For this, they use some heuristics based on + URI syntax. They then allow the user to click on such URIs and + retrieve the corresponding resource in an appropriate (usually + scheme-dependent) application. + + + + + + +Duerst & Suignard Standards Track [Page 33] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + Such applications have to be upgraded to use the IRI syntax as a base + for heuristics. In particular, a non-ASCII character should not be + taken as the indication of the end of an IRI. Such applications also + have to make sure that they correctly convert the detected IRI from + the character encoding of the document or application where the IRI + appears to the character encoding used by the system-wide IRI + invocation mechanism, or to a URI (according to section 3.1) if the + system-wide invocation mechanism only accepts URIs. + + The clipboard is another frequently used way to transfer URIs and + IRIs from one application to another. On most platforms, the + clipboard is able to store and transfer text in many languages and + scripts. Correctly used, the clipboard transfers characters, not + bytes, which will do the right thing with IRIs. + +7.4. URI/IRI Generation + + Systems that offer resources through the Internet, where those + resources have logical names, sometimes automatically generate URIs + for the resources they offer. For example, some HTTP servers can + generate a directory listing for a file directory and then respond to + the generated URIs with the files. + + Many legacy character encodings are in use in various file systems. + Many currently deployed systems do not transform the local character + representation of the underlying system before generating URIs. + + For maximum interoperability, systems that generate resource + identifiers should make the appropriate transformations. For + example, if a file system contains a file named + "résumé.html", a server should expose this as + "r%C3%A9sum%C3%A9.html" in a URI, which allows use of + "résumé.html" in an IRI, even if locally the file name is + kept in a character encoding other than UTF-8. + + This recommendation particularly applies to HTTP servers. For FTP + servers, similar considerations apply; see [RFC2640]. + +7.5. URI/IRI Selection + + In some cases, resource owners and publishers have control over the + IRIs used to identify their resources. This control is mostly + executed by controlling the resource names, such as file names, + directly. + + + + + + + +Duerst & Suignard Standards Track [Page 34] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + In these cases, it is recommended to avoid choosing IRIs that are + easily confused. For example, for US-ASCII, the lower-case ell ("l") + is easily confused with the digit one ("1"), and the upper-case oh + ("O") is easily confused with the digit zero ("0"). Publishers + should avoid confusing users with "br0ken" or "1ame" identifiers. + + Outside the US-ASCII repertoire, there are many more opportunities + for confusion; a complete set of guidelines is too lengthy to include + here. As long as names are limited to characters from a single + script, native writers of a given script or language will know best + when ambiguities can appear, and how they can be avoided. What may + look ambiguous to a stranger may be completely obvious to the average + native user. On the other hand, in some cases, the UCS contains + variants for compatibility reasons; for example, for typographic + purposes. These should be avoided wherever possible. Although there + may be exceptions, newly created resource names should generally be + in NFKC [UTR15] (which means that they are also in NFC). + + As an example, the UCS contains the "fi" ligature at U+FB01 for + compatibility reasons. Wherever possible, IRIs should use the two + letters "f" and "i" rather than the "fi" ligature. An example where + the latter may be used is in the query part of an IRI for an explicit + search for a word written containing the "fi" ligature. + + In certain cases, there is a chance that characters from different + scripts look the same. The best known example is the similarity of + the Latin "A", the Greek "Alpha", and the Cyrillic "A". To avoid + such cases, only IRIs should be created where all the characters in a + single component are used together in a given language. This usually + means that all of these characters will be from the same script, but + there are languages that mix characters from different scripts (such + as Japanese). This is similar to the heuristics used to distinguish + between letters and numbers in the examples above. Also, for Latin, + Greek, and Cyrillic, using lowercase letters results in fewer + ambiguities than using uppercase letters would. + +7.6. Display of URIs/IRIs + + In situations where the rendering software is not expected to display + non-ASCII parts of the IRI correctly using the available layout and + font resources, these parts should be percent-encoded before being + displayed. + + For display of Bidi IRIs, please see section 4.1. + + + + + + + +Duerst & Suignard Standards Track [Page 35] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +7.7. Interpretation of URIs and IRIs + + Software that interprets IRIs as the names of local resources should + accept IRIs in multiple forms and convert and match them with the + appropriate local resource names. + + First, multiple representations include both IRIs in the native + character encoding of the protocol and also their URI counterparts. + + Second, it may include URIs constructed based on character encodings + other than UTF-8. These URIs may be produced by user agents that do + not conform to this specification and that use legacy character + encodings to convert non-ASCII characters to URIs. Whether this is + necessary, and what character encodings to cover, depends on a number + of factors, such as the legacy character encodings used locally and + the distribution of various versions of user agents. For example, + software for Japanese may accept URIs in Shift_JIS and/or EUC-JP in + addition to UTF-8. + + Third, it may include additional mappings to be more user-friendly + and robust against transmission errors. These would be similar to + how some servers currently treat URIs as case insensitive or perform + additional matching to account for spelling errors. For characters + beyond the US-ASCII repertoire, this may, for example, include + ignoring the accents on received IRIs or resource names. Please note + that such mappings, including case mappings, are language dependent. + + It can be difficult to identify a resource unambiguously if too many + mappings are taken into consideration. However, percent-encoded and + not percent-encoded parts of IRIs can always be clearly + distinguished. Also, the regularity of UTF-8 (see [Duerst97]) makes + the potential for collisions lower than it may seem at first. + +7.8. Upgrading Strategy + + Where this recommendation places further constraints on software for + which many instances are already deployed, it is important to + introduce upgrades carefully and to be aware of the various + interdependencies. + + If IRIs cannot be interpreted correctly, they should not be created, + generated, or transported. This suggests that upgrading URI + interpreting software to accept IRIs should have highest priority. + + On the other hand, a single IRI is interpreted only by a single or + very few interpreters that are known in advance, although it may be + entered and transported very widely. + + + + +Duerst & Suignard Standards Track [Page 36] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + Therefore, IRIs benefit most from a broad upgrade of software to be + able to enter and transport IRIs. However, before an individual IRI + is published, care should be taken to upgrade the corresponding + interpreting software in order to cover the forms expected to be + received by various versions of entry and transport software. + + The upgrade of generating software to generate IRIs instead of using + a local character encoding should happen only after the service is + upgraded to accept IRIs. Similarly, IRIs should only be generated + when the service accepts IRIs and the intervening infrastructure and + protocol is known to transport them safely. + + Software converting from URIs to IRIs for display should be upgraded + only after upgraded entry software has been widely deployed to the + population that will see the displayed result. + + Where there is a free choice of character encodings, it is often + possible to reduce the effort and dependencies for upgrading to IRIs + by using UTF-8 rather than another encoding. For example, when a new + file-based Web server is set up, using UTF-8 as the character + encoding for file names will make the transition to IRIs easier. + Likewise, when a new Web form is set up using UTF-8 as the character + encoding of the form page, the returned query URIs will use UTF-8 as + the character encoding (unless the user, for whatever reason, changes + the character encoding) and will therefore be compatible with IRIs. + + These recommendations, when taken together, will allow for the + extension from URIs to IRIs in order to handle characters other than + US-ASCII while minimizing interoperability problems. For + considerations regarding the upgrade of URI scheme definitions, see + section 6.4. + +8. Security Considerations + + The security considerations discussed in [RFC3986] also apply to + IRIs. In addition, the following issues require particular care for + IRIs. + + Incorrect encoding or decoding can lead to security problems. In + particular, some UTF-8 decoders do not check against overlong byte + sequences. As an example, a "/" is encoded with the byte 0x2F both + in UTF-8 and in US-ASCII, but some UTF-8 decoders also wrongly + interpret the sequence 0xC0 0xAF as a "/". A sequence such as + + + + + + + + +Duerst & Suignard Standards Track [Page 37] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + "%C0%AF.." may pass some security tests and then be interpreted as + "/.." in a path if UTF-8 decoders are fault-tolerant, if conversion + and checking are not done in the right order, and/or if reserved + characters and unreserved characters are not clearly distinguished. + + There are various ways in which "spoofing" can occur with IRIs. + "Spoofing" means that somebody may add a resource name that looks the + same or similar to the user, but that points to a different resource. + The added resource may pretend to be the real resource by looking + very similar but may contain all kinds of changes that may be + difficult to spot and that can cause all kinds of problems. Most + spoofing possibilities for IRIs are extensions of those for URIs. + + Spoofing can occur for various reasons. First, a user's + normalization expectations or actual normalization when entering an + IRI or transcoding an IRI from a legacy character encoding do not + match the normalization used on the server side. Conceptually, this + is no different from the problems surrounding the use of + case-insensitive web servers. For example, a popular web page with a + mixed-case name ("http://big.example.com/PopularPage.html") might be + "spoofed" by someone who is able to create + "http://big.example.com/popularpage.html". However, the use of + unnormalized character sequences, and of additional mappings for user + convenience, may increase the chance for spoofing. Protocols and + servers that allow the creation of resources with names that are not + normalized are particularly vulnerable to such attacks. This is an + inherent security problem of the relevant protocol, server, or + resource and is not specific to IRIs, but it is mentioned here for + completeness. + + Spoofing can occur in various IRI components, such as the domain name + part or a path part. For considerations specific to the domain name + part, see [RFC3491]. For the path part, administrators of sites that + allow independent users to create resources in the same sub area may + have to be careful to check for spoofing. + + Spoofing can occur because in the UCS many characters look very + similar. Details are discussed in Section 7.5. Again, this is very + similar to spoofing possibilities on US-ASCII, e.g., using "br0ken" + or "1ame" URIs. + + Spoofing can occur when URIs with percent-encodings based on various + character encodings are accepted to deal with older user agents. In + some cases, particularly for Latin-based resource names, this is + usually easy to detect because UTF-8-encoded names, when interpreted + and viewed as legacy character encodings, produce mostly garbage. + + + + + +Duerst & Suignard Standards Track [Page 38] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + When concurrently used character encodings have a similar structure + but there are no characters that have exactly the same encoding, + detection is more difficult. + + Spoofing can occur with bidirectional IRIs, if the restrictions in + section 4.2 are not followed. The same visual representation may be + interpreted as different logical representations, and vice versa. It + is also very important that a correct Unicode bidirectional + implementation be used. + +9. Acknowledgements + + We would like to thank Larry Masinter for his work as coauthor of + many earlier versions of this document (draft-masinter-url-i18n-xx). + + The discussion on the issue addressed here started a long time ago. + There was a thread in the HTML working group in August 1995 (under + the topic of "Globalizing URIs") and in the www-international mailing + list in July 1996 (under the topic of "Internationalization and + URLs"), and there were ad-hoc meetings at the Unicode conferences in + September 1995 and September 1997. + + Many thanks go to Francois Yergeau, Matitiahu Allouche, Roy Fielding, + Tim Berners-Lee, Mark Davis, M.T. Carrasco Benitez, James Clark, Tim + Bray, Chris Wendt, Yaron Goland, Andrea Vine, Misha Wolf, Leslie + Daigle, Ted Hardie, Bill Fenner, Margaret Wasserman, Russ Housley, + Makoto MURATA, Steven Atkin, Ryan Stansifer, Tex Texin, Graham Klyne, + Bjoern Hoehrmann, Chris Lilley, Ian Jacobs, Adam Costello, Dan + Oscarson, Elliotte Rusty Harold, Mike J. Brown, Roy Badami, Jonathan + Rosenne, Asmus Freytag, Simon Josefsson, Carlos Viegas Damasio, Chris + Haynes, Walter Underwood, and many others for help with understanding + the issues and possible solutions, and with getting the details + right. + + This document is a product of the Internationalization Working Group + (I18N WG) of the World Wide Web Consortium (W3C). Thanks to the + members of the W3C I18N Working Group and Interest Group for their + contributions and their work on [CharMod]. Thanks also go to the + members of many other W3C Working Groups for adopting IRIs, and to + the members of the Montreal IAB Workshop on Internationalization and + Localization for their review. + + + + + + + + + + +Duerst & Suignard Standards Track [Page 39] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +10. References + +10.1. Normative References + + [ASCII] American National Standards Institute, "Coded + Character Set -- 7-bit American Standard Code for + Information Interchange", ANSI X3.4, 1986. + + [ISO10646] International Organization for Standardization, + "ISO/IEC 10646:2003: Information Technology - + Universal Multiple-Octet Coded Character Set (UCS)", + ISO Standard 10646, December 2003. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications + (IDNA)", RFC 3490, March 2003. + + [RFC3491] Hoffman, P. and M. Blanchet, "Nameprep: A Stringprep + Profile for Internationalized Domain Names (IDN)", RFC + 3491, March 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, + "Uniform Resource Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [UNI9] Davis, M., "The Bidirectional Algorithm", Unicode + Standard Annex #9, March 2004, + . + + [UNIV4] The Unicode Consortium, "The Unicode Standard, Version + 4.0.1, defined by: The Unicode Standard, Version 4.0 + (Reading, MA, Addison-Wesley, 2003. ISBN + 0-321-18578-1), as amended by Unicode 4.0.1 + (http://www.unicode.org/versions/Unicode4.0.1/)", + March 2004. + + + + + + + +Duerst & Suignard Standards Track [Page 40] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + [UTR15] Davis, M. and M. Duerst, "Unicode Normalization + Forms", Unicode Standard Annex #15, April 2003, + . + +10.2. Informative References + + [BidiEx] "Examples of bidirectional IRIs", + . + + [CharMod] Duerst, M., Yergeau, F., Ishida, R., Wolf, M., and T. + Texin, "Character Model for the World Wide Web: + Resource Identifiers", World Wide Web Consortium + Candidate Recommendation, November 2004, + . + + [Duerst97] Duerst, M., "The Properties and Promises of UTF-8", + Proc. 11th International Unicode Conference, San Jose + , September 1997, + . + + [Gettys] Gettys, J., "URI Model Consequences", + . + + [HTML4] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 + Specification", World Wide Web Consortium + Recommendation, December 1999, + . + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet + Mail Extensions (MIME) Part One: Format of Internet + Message Bodies", RFC 2045, November 1996. + + [RFC2130] Weider, C., Preston, C., Simonsen, K., Alvestrand, H., + Atkinson, R., Crispin, M., and P. Svanberg, "The + Report of the IAB Character Set Workshop held 29 + February - 1 March, 1996", RFC 2130, April 1997. + + [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. + + [RFC2192] Newman, C., "IMAP URL Scheme", RFC 2192, September + 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + + +Duerst & Suignard Standards Track [Page 41] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + [RFC2368] Hoffman, P., Masinter, L., and J. Zawinski, "The + mailto URL scheme", RFC 2368, July 1998. + + [RFC2384] Gellens, R., "POP URL Scheme", RFC 2384, August 1998. + + [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, + "Uniform Resource Identifiers (URI): Generic Syntax", + RFC 2396, August 1998. + + [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, + August 1998. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, + "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, + June 1999. + + [RFC2640] Curtin, B., "Internationalization of the File Transfer + Protocol", RFC 2640, July 1999. + + [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D., and R. + Petke, "Guidelines for new URL Schemes", RFC 2718, + November 1999. + + [UNIXML] Duerst, M. and A. Freytag, "Unicode in XML and other + Markup Languages", Unicode Technical Report #20, World + Wide Web Consortium Note, June 2003, + . + + [XLink] DeRose, S., Maler, E., and D. Orchard, "XML Linking + Language (XLink) Version 1.0", World Wide Web + Consortium Recommendation, June 2001, + . + + [XML1] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., + and F. Yergeau, "Extensible Markup Language (XML) 1.0 + (Third Edition)", World Wide Web Consortium + Recommendation, February 2004, + . + + [XMLNamespace] Bray, T., Hollander, D., and A. Layman, "Namespaces in + XML", World Wide Web Consortium Recommendation, + January 1999, . + + [XMLSchema] Biron, P. and A. Malhotra, "XML Schema Part 2: + Datatypes", World Wide Web Consortium Recommendation, + May 2001, . + + + + +Duerst & Suignard Standards Track [Page 42] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + [XPointer] Grosso, P., Maler, E., Marsh, J. and N. Walsh, + "XPointer Framework", World Wide Web Consortium + Recommendation, March 2003, + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Duerst & Suignard Standards Track [Page 43] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +Appendix A. Design Alternatives + + This section shortly summarizes major design alternatives and the + reasons for why they were not chosen. + +Appendix A.1. New Scheme(s) + + Introducing new schemes (for example, httpi:, ftpi:,...) or a new + metascheme (e.g., i:, leading to URI/IRI prefixes such as i:http:, + i:ftp:,...) was proposed to make IRI-to-URI conversion scheme + dependent or to distinguish between percent-encodings resulting from + IRI-to-URI conversion and percent-encodings from legacy character + encodings. + + New schemes are not needed to distinguish URIs from true IRIs (i.e., + IRIs that contain non-ASCII characters). The benefit of being able + to detect the origin of percent-encodings is marginal, as UTF-8 can + be detected with very high reliability. Deploying new schemes is + extremely hard, so not requiring new schemes for IRIs makes + deployment of IRIs vastly easier. Making conversion scheme dependent + is highly inadvisable and would be encouraged by separate schemes for + IRIs. Using a uniform convention for conversion from IRIs to URIs + makes IRI implementation orthogonal to the introduction of actual new + schemes. + +Appendix A.2. Character Encodings Other Than UTF-8 + + At an early stage, UTF-7 was considered as an alternative to UTF-8 + when IRIs are converted to URIs. UTF-7 would not have needed + percent-encoding and in most cases would have been shorter than + percent-encoded UTF-8. + + Using UTF-8 avoids a double layering and overloading of the use of + the "+" character. UTF-8 is fully compatible with US-ASCII and has + therefore been recommended by the IETF, and is being used widely. + + UTF-7 has never been used much and is now clearly being discouraged. + Requiring implementations to convert from UTF-8 to UTF-7 and back + would be an additional implementation burden. + +Appendix A.3. New Encoding Convention + + Instead of using the existing percent-encoding convention of URIs, + which is based on octets, the idea was to create a new encoding + convention; for example, to use "%u" to introduce UCS code points. + + + + + + +Duerst & Suignard Standards Track [Page 44] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + + Using the existing octet-based percent-encoding mechanism does not + need an upgrade of the URI syntax and does not need corresponding + server upgrades. + +Appendix A.4. Indicating Character Encodings in the URI/IRI + + Some proposals suggested indicating the character encodings used in + an URI or IRI with some new syntactic convention in the URI itself, + similar to the "charset" parameter for e-mails and Web pages. As an + example, the label in square brackets in + "http://www.example.org/ros[iso-8859-1]é"; indicated that the + following "é"; had to be interpreted as iso-8859-1. + + If UTF-8 is used exclusively, an upgrade to the URI syntax is not + needed. It avoids potentially multiple labels that have to be copied + correctly in all cases, even on the side of a bus or on a napkin, + leading to usability problems (and being prohibitively annoying). + Exclusively using UTF-8 also reduces transcoding errors and + confusion. + +Authors' Addresses + + Martin Duerst (Note: Please write "Duerst" with u-umlaut wherever + possible, for example as "Dürst" in XML and + HTML.) + World Wide Web Consortium + 5322 Endo + Fujisawa, Kanagawa 252-8520 + Japan + + Phone: +81 466 49 1170 + Fax: +81 466 49 1171 + EMail: duerst@w3.org + URI: http://www.w3.org/People/D%C3%BCrst/ + (Note: This is the percent-encoded form of an IRI.) + + + Michel Suignard + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + U.S.A. + + Phone: +1 425 882-8080 + EMail: michelsu@microsoft.com + URI: http://www.suignard.com + + + + + +Duerst & Suignard Standards Track [Page 45] + +RFC 3987 Internationalized Resource Identifiers January 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the IETF's procedures with respect to rights in IETF Documents can + be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Duerst & Suignard Standards Track [Page 46] + diff --git a/docs/standards/references/rfc8259.txt b/docs/standards/references/rfc8259.txt new file mode 100644 index 0000000..f1adf81 --- /dev/null +++ b/docs/standards/references/rfc8259.txt @@ -0,0 +1,899 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Bray, Ed. +Request for Comments: 8259 Textuality +Obsoletes: 7159 December 2017 +Category: Standards Track +ISSN: 2070-1721 + + + The JavaScript Object Notation (JSON) Data Interchange Format + +Abstract + + JavaScript Object Notation (JSON) is a lightweight, text-based, + language-independent data interchange format. It was derived from + the ECMAScript Programming Language Standard. JSON defines a small + set of formatting rules for the portable representation of structured + data. + + This document removes inconsistencies with other specifications of + JSON, repairs specification errors, and offers experience-based + interoperability guidance. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8259. + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 1] + +RFC 8259 JSON December 2017 + + +Copyright Notice + + Copyright (c) 2017 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + + + + + + + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 2] + +RFC 8259 JSON December 2017 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 + 1.2. Specifications of JSON . . . . . . . . . . . . . . . . . 4 + 1.3. Introduction to This Revision . . . . . . . . . . . . . . 5 + 2. JSON Grammar . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3. Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 6. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 7. Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 8. String and Character Issues . . . . . . . . . . . . . . . . . 9 + 8.1. Character Encoding . . . . . . . . . . . . . . . . . . . 9 + 8.2. Unicode Characters . . . . . . . . . . . . . . . . . . . 10 + 8.3. String Comparison . . . . . . . . . . . . . . . . . . . . 10 + 9. Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 10. Generators . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 + 12. Security Considerations . . . . . . . . . . . . . . . . . . . 12 + 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 14 + 14.2. Informative References . . . . . . . . . . . . . . . . . 14 + Appendix A. Changes from RFC 7159 . . . . . . . . . . . . . . . 16 + Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 + +1. Introduction + + JavaScript Object Notation (JSON) is a text format for the + serialization of structured data. It is derived from the object + literals of JavaScript, as defined in the ECMAScript Programming + Language Standard, Third Edition [ECMA-262]. + + JSON can represent four primitive types (strings, numbers, booleans, + and null) and two structured types (objects and arrays). + + A string is a sequence of zero or more Unicode characters [UNICODE]. + Note that this citation references the latest version of Unicode + rather than a specific release. It is not expected that future + changes in the Unicode specification will impact the syntax of JSON. + + An object is an unordered collection of zero or more name/value + pairs, where a name is a string and a value is a string, number, + boolean, null, object, or array. + + An array is an ordered sequence of zero or more values. + + + +Bray Standards Track [Page 3] + +RFC 8259 JSON December 2017 + + + The terms "object" and "array" come from the conventions of + JavaScript. + + JSON's design goals were for it to be minimal, portable, textual, and + a subset of JavaScript. + +1.1. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in BCP + 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The grammatical rules in this document are to be interpreted as + described in [RFC5234]. + +1.2. Specifications of JSON + + This document replaces [RFC7159]. [RFC7159] obsoleted [RFC4627], + which originally described JSON and registered the media type + "application/json". + + JSON is also described in [ECMA-404]. + + The reference to ECMA-404 in the previous sentence is normative, not + with the usual meaning that implementors need to consult it in order + to understand this document, but to emphasize that there are no + inconsistencies in the definition of the term "JSON text" in any of + its specifications. Note, however, that ECMA-404 allows several + practices that this specification recommends avoiding in the + interests of maximal interoperability. + + The intent is that the grammar is the same between the two documents, + although different descriptions are used. If there is a difference + found between them, ECMA and the IETF will work together to update + both documents. + + If an error is found with either document, the other should be + examined to see if it has a similar error; if it does, it should be + fixed, if possible. + + If either document is changed in the future, ECMA and the IETF will + work together to ensure that the two documents stay aligned through + the change. + + + + + + +Bray Standards Track [Page 4] + +RFC 8259 JSON December 2017 + + +1.3. Introduction to This Revision + + In the years since the publication of RFC 4627, JSON has found very + wide use. This experience has revealed certain patterns that, while + allowed by its specifications, have caused interoperability problems. + + Also, a small number of errata have been reported regarding RFC 4627 + (see RFC Errata IDs 607 [Err607] and 3607 [Err3607]) and regarding + RFC 7159 (see RFC Errata IDs 3915 [Err3915], 4264 [Err4264], 4336 + [Err4336], and 4388 [Err4388]). + + This document's goal is to apply the errata, remove inconsistencies + with other specifications of JSON, and highlight practices that can + lead to interoperability problems. + +2. JSON Grammar + + A JSON text is a sequence of tokens. The set of tokens includes six + structural characters, strings, numbers, and three literal names. + + A JSON text is a serialized value. Note that certain previous + specifications of JSON constrained a JSON text to be an object or an + array. Implementations that generate only objects or arrays where a + JSON text is called for will be interoperable in the sense that all + implementations will accept these as conforming JSON texts. + + JSON-text = ws value ws + + These are the six structural characters: + + begin-array = ws %x5B ws ; [ left square bracket + + begin-object = ws %x7B ws ; { left curly bracket + + end-array = ws %x5D ws ; ] right square bracket + + end-object = ws %x7D ws ; } right curly bracket + + name-separator = ws %x3A ws ; : colon + + value-separator = ws %x2C ws ; , comma + + + + + + + + + + +Bray Standards Track [Page 5] + +RFC 8259 JSON December 2017 + + + Insignificant whitespace is allowed before or after any of the six + structural characters. + + ws = *( + %x20 / ; Space + %x09 / ; Horizontal tab + %x0A / ; Line feed or New line + %x0D ) ; Carriage return + +3. Values + + A JSON value MUST be an object, array, number, or string, or one of + the following three literal names: + + false + null + true + + The literal names MUST be lowercase. No other literal names are + allowed. + + value = false / null / true / object / array / number / string + + false = %x66.61.6c.73.65 ; false + + null = %x6e.75.6c.6c ; null + + true = %x74.72.75.65 ; true + +4. Objects + + An object structure is represented as a pair of curly brackets + surrounding zero or more name/value pairs (or members). A name is a + string. A single colon comes after each name, separating the name + from the value. A single comma separates a value from a following + name. The names within an object SHOULD be unique. + + object = begin-object [ member *( value-separator member ) ] + end-object + + member = string name-separator value + + An object whose names are all unique is interoperable in the sense + that all software implementations receiving that object will agree on + the name-value mappings. When the names within an object are not + unique, the behavior of software that receives such an object is + unpredictable. Many implementations report the last name/value pair + only. Other implementations report an error or fail to parse the + + + +Bray Standards Track [Page 6] + +RFC 8259 JSON December 2017 + + + object, and some implementations report all of the name/value pairs, + including duplicates. + + JSON parsing libraries have been observed to differ as to whether or + not they make the ordering of object members visible to calling + software. Implementations whose behavior does not depend on member + ordering will be interoperable in the sense that they will not be + affected by these differences. + +5. Arrays + + An array structure is represented as square brackets surrounding zero + or more values (or elements). Elements are separated by commas. + + array = begin-array [ value *( value-separator value ) ] end-array + + There is no requirement that the values in an array be of the same + type. + +6. Numbers + + The representation of numbers is similar to that used in most + programming languages. A number is represented in base 10 using + decimal digits. It contains an integer component that may be + prefixed with an optional minus sign, which may be followed by a + fraction part and/or an exponent part. Leading zeros are not + allowed. + + A fraction part is a decimal point followed by one or more digits. + + An exponent part begins with the letter E in uppercase or lowercase, + which may be followed by a plus or minus sign. The E and optional + sign are followed by one or more digits. + + Numeric values that cannot be represented in the grammar below (such + as Infinity and NaN) are not permitted. + + number = [ minus ] int [ frac ] [ exp ] + + decimal-point = %x2E ; . + + digit1-9 = %x31-39 ; 1-9 + + e = %x65 / %x45 ; e E + + exp = e [ minus / plus ] 1*DIGIT + + frac = decimal-point 1*DIGIT + + + +Bray Standards Track [Page 7] + +RFC 8259 JSON December 2017 + + + int = zero / ( digit1-9 *DIGIT ) + + minus = %x2D ; - + + plus = %x2B ; + + + zero = %x30 ; 0 + + This specification allows implementations to set limits on the range + and precision of numbers accepted. Since software that implements + IEEE 754 binary64 (double precision) numbers [IEEE754] is generally + available and widely used, good interoperability can be achieved by + implementations that expect no more precision or range than these + provide, in the sense that implementations will approximate JSON + numbers within the expected precision. A JSON number such as 1E400 + or 3.141592653589793238462643383279 may indicate potential + interoperability problems, since it suggests that the software that + created it expects receiving software to have greater capabilities + for numeric magnitude and precision than is widely available. + + Note that when such software is used, numbers that are integers and + are in the range [-(2**53)+1, (2**53)-1] are interoperable in the + sense that implementations will agree exactly on their numeric + values. + +7. Strings + + The representation of strings is similar to conventions used in the C + family of programming languages. A string begins and ends with + quotation marks. All Unicode characters may be placed within the + quotation marks, except for the characters that MUST be escaped: + quotation mark, reverse solidus, and the control characters (U+0000 + through U+001F). + + Any character may be escaped. If the character is in the Basic + Multilingual Plane (U+0000 through U+FFFF), then it may be + represented as a six-character sequence: a reverse solidus, followed + by the lowercase letter u, followed by four hexadecimal digits that + encode the character's code point. The hexadecimal letters A through + F can be uppercase or lowercase. So, for example, a string + containing only a single reverse solidus character may be represented + as "\u005C". + + Alternatively, there are two-character sequence escape + representations of some popular characters. So, for example, a + string containing only a single reverse solidus character may be + represented more compactly as "\\". + + + + +Bray Standards Track [Page 8] + +RFC 8259 JSON December 2017 + + + To escape an extended character that is not in the Basic Multilingual + Plane, the character is represented as a 12-character sequence, + encoding the UTF-16 surrogate pair. So, for example, a string + containing only the G clef character (U+1D11E) may be represented as + "\uD834\uDD1E". + + string = quotation-mark *char quotation-mark + + char = unescaped / + escape ( + %x22 / ; " quotation mark U+0022 + %x5C / ; \ reverse solidus U+005C + %x2F / ; / solidus U+002F + %x62 / ; b backspace U+0008 + %x66 / ; f form feed U+000C + %x6E / ; n line feed U+000A + %x72 / ; r carriage return U+000D + %x74 / ; t tab U+0009 + %x75 4HEXDIG ) ; uXXXX U+XXXX + + escape = %x5C ; \ + + quotation-mark = %x22 ; " + + unescaped = %x20-21 / %x23-5B / %x5D-10FFFF + +8. String and Character Issues + +8.1. Character Encoding + + JSON text exchanged between systems that are not part of a closed + ecosystem MUST be encoded using UTF-8 [RFC3629]. + + Previous specifications of JSON have not required the use of UTF-8 + when transmitting JSON text. However, the vast majority of JSON- + based software implementations have chosen to use the UTF-8 encoding, + to the extent that it is the only encoding that achieves + interoperability. + + Implementations MUST NOT add a byte order mark (U+FEFF) to the + beginning of a networked-transmitted JSON text. In the interests of + interoperability, implementations that parse JSON texts MAY ignore + the presence of a byte order mark rather than treating it as an + error. + + + + + + + +Bray Standards Track [Page 9] + +RFC 8259 JSON December 2017 + + +8.2. Unicode Characters + + When all the strings represented in a JSON text are composed entirely + of Unicode characters [UNICODE] (however escaped), then that JSON + text is interoperable in the sense that all software implementations + that parse it will agree on the contents of names and of string + values in objects and arrays. + + However, the ABNF in this specification allows member names and + string values to contain bit sequences that cannot encode Unicode + characters; for example, "\uDEAD" (a single unpaired UTF-16 + surrogate). Instances of this have been observed, for example, when + a library truncates a UTF-16 string without checking whether the + truncation split a surrogate pair. The behavior of software that + receives JSON texts containing such values is unpredictable; for + example, implementations might return different values for the length + of a string value or even suffer fatal runtime exceptions. + +8.3. String Comparison + + Software implementations are typically required to test names of + object members for equality. Implementations that transform the + textual representation into sequences of Unicode code units and then + perform the comparison numerically, code unit by code unit, are + interoperable in the sense that implementations will agree in all + cases on equality or inequality of two strings. For example, + implementations that compare strings with escaped characters + unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not + equal. + +9. Parsers + + A JSON parser transforms a JSON text into another representation. A + JSON parser MUST accept all texts that conform to the JSON grammar. + A JSON parser MAY accept non-JSON forms or extensions. + + An implementation may set limits on the size of texts that it + accepts. An implementation may set limits on the maximum depth of + nesting. An implementation may set limits on the range and precision + of numbers. An implementation may set limits on the length and + character contents of strings. + +10. Generators + + A JSON generator produces JSON text. The resulting text MUST + strictly conform to the JSON grammar. + + + + + +Bray Standards Track [Page 10] + +RFC 8259 JSON December 2017 + + +11. IANA Considerations + + The media type for JSON text is application/json. + + Type name: application + + Subtype name: json + + Required parameters: n/a + + Optional parameters: n/a + + Encoding considerations: binary + + Security considerations: See RFC 8259, Section 12 + + Interoperability considerations: Described in RFC 8259 + + Published specification: RFC 8259 + + Applications that use this media type: + JSON has been used to exchange data between applications written + in all of these programming languages: ActionScript, C, C#, + Clojure, ColdFusion, Common Lisp, E, Erlang, Go, Java, JavaScript, + Lua, Objective CAML, Perl, PHP, Python, Rebol, Ruby, Scala, and + Scheme. + + Additional information: + Magic number(s): n/a + File extension(s): .json + Macintosh file type code(s): TEXT + + Person & email address to contact for further information: + IESG + + + Intended usage: COMMON + + Restrictions on usage: none + + Author: + Douglas Crockford + + + Change controller: + IESG + + + + + +Bray Standards Track [Page 11] + +RFC 8259 JSON December 2017 + + + Note: No "charset" parameter is defined for this registration. + Adding one really has no effect on compliant recipients. + +12. Security Considerations + + Generally, there are security issues with scripting languages. JSON + is a subset of JavaScript but excludes assignment and invocation. + + Since JSON's syntax is borrowed from JavaScript, it is possible to + use that language's "eval()" function to parse most JSON texts (but + not all; certain characters such as U+2028 LINE SEPARATOR and U+2029 + PARAGRAPH SEPARATOR are legal in JSON but not JavaScript). This + generally constitutes an unacceptable security risk, since the text + could contain executable code along with data declarations. The same + consideration applies to the use of eval()-like functions in any + other programming language in which JSON texts conform to that + language's syntax. + +13. Examples + + This is a JSON object: + + { + "Image": { + "Width": 800, + "Height": 600, + "Title": "View from 15th Floor", + "Thumbnail": { + "Url": "http://www.example.com/image/481989943", + "Height": 125, + "Width": 100 + }, + "Animated" : false, + "IDs": [116, 943, 234, 38793] + } + } + + Its Image member is an object whose Thumbnail member is an object and + whose IDs member is an array of numbers. + + + + + + + + + + + + +Bray Standards Track [Page 12] + +RFC 8259 JSON December 2017 + + + This is a JSON array containing two objects: + + [ + { + "precision": "zip", + "Latitude": 37.7668, + "Longitude": -122.3959, + "Address": "", + "City": "SAN FRANCISCO", + "State": "CA", + "Zip": "94107", + "Country": "US" + }, + { + "precision": "zip", + "Latitude": 37.371991, + "Longitude": -122.026020, + "Address": "", + "City": "SUNNYVALE", + "State": "CA", + "Zip": "94085", + "Country": "US" + } + ] + + Here are three small JSON texts containing only values: + + "Hello world!" + + 42 + + true + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 13] + +RFC 8259 JSON December 2017 + + +14. References + +14.1. Normative References + + [ECMA-404] Ecma International, "The JSON Data Interchange Format", + Standard ECMA-404, + . + + [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", + IEEE 754. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [UNICODE] The Unicode Consortium, "The Unicode Standard", + . + +14.2. Informative References + + [ECMA-262] Ecma International, "ECMAScript Language Specification", + Standard ECMA-262, Third Edition, December 1999, + . + + [Err3607] RFC Errata, Erratum ID 3607, RFC 4627, + . + + [Err3915] RFC Errata, Erratum ID 3915, RFC 7159, + . + + + + + +Bray Standards Track [Page 14] + +RFC 8259 JSON December 2017 + + + [Err4264] RFC Errata, Erratum ID 4264, RFC 7159, + . + + [Err4336] RFC Errata, Erratum ID 4336, RFC 7159, + . + + [Err4388] RFC Errata, Erratum ID 4388, RFC 7159, + . + + [Err607] RFC Errata, Erratum ID 607, RFC 4627, + . + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, + DOI 10.17487/RFC4627, July 2006, + . + + [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data + Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March + 2014, . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bray Standards Track [Page 15] + +RFC 8259 JSON December 2017 + + +Appendix A. Changes from RFC 7159 + + This section lists changes between this document and the text in + RFC 7159. + + o Section 1.2 has been updated to reflect the removal of a JSON + specification from ECMA-262, to make ECMA-404 a normative + reference, and to explain the particular meaning of "normative". + + o Section 1.3 has been updated to reflect errata filed against + RFC 7159, not RFC 4627. + + o Section 8.1 was changed to require the use of UTF-8 when + transmitted over a network. + + o Section 12 has been updated to increase the precision of the + description of the security risk that follows from using the + ECMAScript "eval()" function. + + o Section 14.1 has been updated to include ECMA-404 as a normative + reference. + + o Section 14.2 has been updated to remove ECMA-404, update the + version of ECMA-262, and refresh the errata list. + +Contributors + + RFC 4627 was written by Douglas Crockford. This document was + constructed by making a relatively small number of changes to that + document; thus, the vast majority of the text here is his. + +Author's Address + + Tim Bray (editor) + Textuality + + Email: tbray@textuality.com + + + + + + + + + + + + + + +Bray Standards Track [Page 16] + diff --git a/docs/standards/references/trig.html b/docs/standards/references/trig.html new file mode 100644 index 0000000..511d3cd --- /dev/null +++ b/docs/standards/references/trig.html @@ -0,0 +1,1515 @@ + + + + RDF 1.1 TriG + + + + + + + + + + + + + +

Abstract

+

This document defines a textual syntax for RDF called TriG + that allows an RDF dataset to be completely written in a compact and + natural text form, with abbreviations for common usage patterns and + datatypes. TriG is an extension of the + Turtle [TURTLE] format. +

+

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

This document is part of the RDF 1.1 document suite. +TriG is intended the meet the charter requirement of the +RDF Working Group to +define an RDF syntax for multiple graphs. TriG is an extension of the +Turtle +syntax for RDF [TURTLE]. The current document is based on +the original proposal by Chris Bizer and Richard Cyganiak.

+ + +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ +

+ Please see the Working Group's implementation + report. +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + +
+ + +

1. Introduction

+

This document defines TriG, a concrete syntax for RDF as defined in the + RDF Concepts and Abstract Syntax document + [RDF11-CONCEPTS]. TriG is an extension of + Turtle [TURTLE], extended + to support representing a complete RDF Dataset. +

+ +
+ + +

2. TriG Language

This section is non-normative.

+ +

A TriG document allows writing down an RDF Dataset in a compact + textual form. It consists of a sequence of directives, triple statements, graph statements which contain triple-generating statements and optional blank lines. + Comments may be given after a # that is not part of another + lexical token and continue to the end of the line.

+

+ +

Graph statements are a pair of an IRI or blank node label and a group of triple statements + surrounded by {}. The IRI or blank node label of the graph statement may be used in another graph statement which implies taking the union of the tripes generated + by each graph statement. An IRI or blank node label used as a graph label may also reoccur as part of any triple statement. + Optionally a graph statement may not not be labeled with an IRI. Such a + graph statement corresponds to the Default Graph of an RDF Dataset.

+

+ The construction of an RDF Dataset from a TriG document is defined in section 4. TriG Grammar and section 5. Parsing. +

+ +
+

2.1 Triple Statements

+

As TriG is an extention of the Turtle language it allows for any constructs from the Turtle language. Simple Triples, Predicate Lists, and Object Lists can all be used either inside a graph statement, or on their own as in a Turtle document. When outside a graph statement, the triples are considered to be part of the default graph of the RDF Dataset.

+
+ +
+

2.2 Graph Statements

+ +

A graph statement pairs an IRI or blank node with a RDF graph. The triple statements that make up the graph are enclosed in {}.

+ +

In a TriG document a graph IRI or blank node may be used as label for more than one graph statements. The graph label of a graph statement may be omitted. In this case the graph is considered the default graph of the RDF Dataset.

+ +

A RDF Dataset might contain only a single graph.

+
Example 1
# This document encodes one graph.
+@prefix ex: <http://www.example.org/vocabulary#> .
+@prefix : <http://www.example.org/exampleDocument#> .
+
+:G1 { :Monica a ex:Person ;
+              ex:name "Monica Murphy" ;
+              ex:homepage <http://www.monicamurphy.org> ;
+              ex:email <mailto:monica@monicamurphy.org> ;
+              ex:hasSkill ex:Management ,
+                          ex:Programming . }
+
+

A RDF Dataset may contain a default graph, and named graphs.

+
Example 2
# This document contains a default graph and two named graphs.
+
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix dc: <http://purl.org/dc/terms/> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+# default graph
+    {
+      <http://example.org/bob> dc:publisher "Bob" .
+      <http://example.org/alice> dc:publisher "Alice" .
+    }
+
+<http://example.org/bob>
+    {
+       _:a foaf:name "Bob" .
+       _:a foaf:mbox <mailto:bob@oldcorp.example.org> .
+       _:a foaf:knows _:b .
+    }
+
+<http://example.org/alice>
+    {
+       _:b foaf:name "Alice" .
+       _:b foaf:mbox <mailto:alice@work.example.org> .
+    }
+ +

TriG provides various alternative ways to write graphs +and triples, giving the data writer choices for clarity: +

+ +
Example 3
# This document contains a same data as the
+previous example.
+
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix dc: <http://purl.org/dc/terms/> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+# default graph - no {} used.
+<http://example.org/bob> dc:publisher "Bob" .
+<http://example.org/alice> dc:publisher "Alice" .
+
+# GRAPH keyword to highlight a named graph
+# Abbreviation of triples using ;
+GRAPH <http://example.org/bob>
+{
+   [] foaf:name "Bob" ;
+      foaf:mbox <mailto:bob@oldcorp.example.org> ;
+      foaf:knows _:b .
+}
+
+GRAPH <http://example.org/alice>
+{
+    _:b foaf:name "Alice" ;
+        foaf:mbox <mailto:alice@work.example.org>
+}
+ + +
+ +
+

2.3 Other Terms

+

All other terms and directives come from Turtle.

+
+

2.3.1 Special Considerations for Blank Nodes

+

BlankNodes sharing the same label in differently labeled graph statements are considered to be the same BlankNode.

+
+
+
+ + + +
+ +

3. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

+ The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, + and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. +

+ +

This specification defines conformance criteria for:

+
    +
  • TriG documents +
  • TriG parsers +
+

A conforming TriG document is a Unicode string that conforms to the grammar and additional constraints defined in section 4. TriG Grammar, starting with the trigDoc production. A TriG document serializes an RDF dataset.

+ +

A conforming TriG parser is a system capable of reading TriG documents on behalf of an application. It makes the serialized RDF dataset, as defined in section 5. Parsing, available to the application, usually through some form of API.

+ +

The IRI that identifies the TriG language is: http://www.w3.org/ns/formats/TriG

+ +
Note

This specification does not define how TriG parsers handle non-conforming input documents.

+
+

3.1 Media Type and Content Encoding

+ +

The media type of TriG is application/trig. + The content encoding of TriG content is always UTF-8. +

+
+
+ +
+ + +

4. TriG Grammar

+ + +

A TriG document is a Unicode [UNICODE] character string + encoded in UTF-8. + Unicode characters only in the range U+0000 to U+10FFFF inclusive are + allowed. +

+
+

4.1 White Space

+

White space (production WS) is used to separate two terminals which would otherwise be (mis-)recognized as one terminal. Rule names below in capitals indicate where white space is significant; these form a possible choice of terminals for constructing a TriG parser.

+ +

White space is significant in the production String.

+
+
+

4.2 Comments

+ +

Comments in TriG take the form of '#', outside an + + IRI or a string, + and continue to the end of line (marked by characters U+000D or U+000A) + or end of file if there is no end of line after the comment + marker. Comments are treated as white space. +

+
+
+

4.3 IRI References

+

+ Relative IRIs are resolved with base IRIs as per Uniform Resource Identifier (URI): Generic Syntax [RFC3986] using only the basic algorithm in section 5.2. + Neither Syntax-Based Normalization nor Scheme-Based Normalization (described in sections 6.2.2 and 6.2.3 of RFC3986) are performed. + Characters additionally allowed in IRI references are treated in the same way that unreserved characters are treated in URI references, per section 6.5 of Internationalized Resource Identifiers (IRIs) [RFC3987]. +

+

+ The @base directive defines the Base IRI used to resolve relative IRIs per RFC3986 section 5.1.1, "Base URI Embedded in Content". + Section 5.1.2, "Base URI from the Encapsulating Entity" defines how the In-Scope Base IRI may come from an encapsulating document, such as a SOAP envelope with an xml:base directive or a mime multipart document with a Content-Location header. + The "Retrieval URI" identified in 5.1.3, Base "URI from the Retrieval URI", is the URL from which a particular TriG document was retrieved. + If none of the above specifies the Base URI, the default Base URI (section 5.1.4, "Default Base URI") is used. + Each @base directive sets a new In-Scope Base URI, relative to the previous one. +

+
+
+

4.4 Escape Sequences

+ +

+ There are three forms of escapes used in TriG documents: +

+ +
    +
  • +

    + numeric escape sequences represent Unicode code points: +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Escape sequenceUnicode code point
    '\u' hex hex hex hexA Unicode character in the range U+0000 to U+FFFF inclusive + corresponding to the value encoded by the four hexadecimal digits interpreted from most significant to least significant digit.
    '\U' hex hex hex hex hex hex hex hexA Unicode character in the range U+0000 to U+10FFFF inclusive + corresponding to the value encoded by the eight hexadecimal digits interpreted from most significant to least significant digit.
    + +

    where HEX is a hexadecimal character

    +
    +

    HEX + ::= [0-9] | [A-F] | [a-f]

    + +
    +
    • + +
  • +

    + string escape sequences represent the characters traditionally escaped in string literals: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Escape sequenceUnicode code point
    '\t'U+0009
    '\b'U+0008
    '\n'U+000A
    '\r'U+000D
    '\f'U+000C
    '\"'U+0022
    '\''U+0027
    '\\'U+005C
    +
    • + +
  • +

    + reserved character escape sequences consist of a '\' followed by one of ~.-!$&'()*+,;=/?#@%_ and represent the character to the right of the '\'. +

    +
    • + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Context where each kind of escape sequence can be used
numeric
escapes		string
escapes		reserved character
escapes
IRIs, used as RDF terms or as in @prefix or @base declarationsyesnono
local namesnonoyes
Stringsyesyesno
+
Note

%-encoded sequences are in the character range for IRIs and are explicitly allowed in local names. These appear as a '%' followed by two hex characters and represent that same sequence of three characters. These sequences are not decoded during processing. A term written as <http://a.example/%66oo-bar> in TriG designates the IRI http://a.example/%66oo-bar and not IRI http://a.example/foo-bar. A term written as ex:%66oo-bar with a prefix @prefix ex: <http://a.example/> also designates the IRI http://a.example/%66oo-bar.

+ +
+
+

4.5 Grammar

+ +

The EBNF used here is defined in XML 1.0 + [EBNF-NOTATION]. Production labels consisting of a number and a final 'g' are unique to TriG. All Production labels consisting of only a number reference the production with that number in the +Turtle grammar +[TURTLE]. Production labels consisting of a number and a final 's', + e.g. [60s], reference the production + with that number in the document SPARQL 1.1 Query Language grammar [SPARQL11-QUERY]. +

+ + +
+

Notes:

+
    +
  1. A blank node label represents the same blank node + throughout the TriG document. +
    2. +
  2. + Keywords in single quotes ( + '@base', + '@prefix', + 'a', + 'true', + 'false') are + case-sensitive. + Keywords in double quotes ( + "BASE", + "PREFIX" + "GRAPH" + ) are case-insensitive. +
    3. +
  3. + Escape sequences markers \u, \U + and those in ECHAR + are case sensitive. +
    4. +
  4. + When tokenizing the input and choosing grammar rules, the longest match is chosen. +
    5. +
  5. + The TriG grammar is LL(1) and LALR(1) when the rules with uppercased names are used as terminals. +
    6. +
  6. + The entry point into the grammar is trigDoc. +
    7. +
  7. + In signed numbers, no white space is allowed between the sign and the number. +
    8. +
  8. + The + + [162s] + ANON + ::= + '[' WS* ']' + + token allows any amount of white space and comments between []s. + The single space version is used in the grammar for clarity. +
    9. +
  9. + The strings '@prefix' and '@base' match the pattern for LANGTAG, though neither "prefix" nor "base" are registered language +subtags. + This specification does not define whether a quoted literal followed by either of these tokens (e.g. "Z"@base) is in the TriG language. +
    10. +
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1g]trigDoc::=(directive | block)*
[2g]block::=triplesOrGraph | wrappedGraph | triples2 | "GRAPH" labelOrSubject wrappedGraph
[3g]triplesOrGraph::=labelOrSubject (wrappedGraph | predicateObjectList '.')
[4g]triples2::=blankNodePropertyList + predicateObjectList? + '.' + | + collection + predicateObjectList + '.' +
[5g]wrappedGraph::='{' triplesBlock? '}'
[6g]triplesBlock::=triples ('.' triplesBlock?)?
[7g]labelOrSubject::=iri | BlankNode
[3]directive::=prefixID | base | sparqlPrefix | sparqlBase
[4]prefixID::='@prefix' PNAME_NS IRIREF '.'
[5]base::='@base' IRIREF '.'
[5s]sparqlPrefix::="PREFIX" PNAME_NS IRIREF
[6s]sparqlBase::="BASE" IRIREF
[6]triples::=subject predicateObjectList | blankNodePropertyList predicateObjectList?
[7]predicateObjectList::=verb objectList (';' (verb objectList)?)*
[8]objectList::=object (',' object)*
[9]verb::=predicate | 'a'
[10]subject::=iri | blank
[11]predicate::=iri
[12]object::=iri | blank | blankNodePropertyList | literal
[13]literal::=RDFLiteral | NumericLiteral | BooleanLiteral
[14]blank::=BlankNode | collection
[15]blankNodePropertyList::='[' predicateObjectList ']'
[16]collection::='(' object* ')'
[17]NumericLiteral::=INTEGER | DECIMAL | DOUBLE
[128s]RDFLiteral::=String (LANGTAG | '^^' iri)?
[133s]BooleanLiteral::='true' | 'false'
[18]String::=STRING_LITERAL_QUOTE | STRING_LITERAL_SINGLE_QUOTE | STRING_LITERAL_LONG_SINGLE_QUOTE | STRING_LITERAL_LONG_QUOTE
[135s]iri::=IRIREF | PrefixedName
[136s]PrefixedName::=PNAME_LN | PNAME_NS
[137s]BlankNode::=BLANK_NODE_LABEL | ANON

Productions for terminals

[19]IRIREF::='<' ([^#x00-#x20<>"{}|^`\] | UCHAR)* '>'
[139s]PNAME_NS::=PN_PREFIX? ':'
[140s]PNAME_LN::=PNAME_NS PN_LOCAL
[141s]BLANK_NODE_LABEL::='_:' (PN_CHARS_U | [0-9]) ((PN_CHARS | '.')* PN_CHARS)?
[144s]LANGTAG::='@' [a-zA-Z]+ ('-' [a-zA-Z0-9]+)*
[20]INTEGER::=[+-]? [0-9]+
[21]DECIMAL::=[+-]? ([0-9]* '.' [0-9]+)
[22]DOUBLE::=[+-]? ([0-9]+ '.' [0-9]* EXPONENT | '.' [0-9]+ EXPONENT | [0-9]+ EXPONENT)
[154s]EXPONENT::=[eE] [+-]? [0-9]+
[23]STRING_LITERAL_QUOTE::='"' ([^#x22#x5C#xA#xD] | ECHAR | UCHAR)* '"'
[24]STRING_LITERAL_SINGLE_QUOTE::="'" ([^#x27#x5C#xA#xD] | ECHAR | UCHAR)* "'"
[25]STRING_LITERAL_LONG_SINGLE_QUOTE::="'''" (("'" | "''")? ([^'\] | ECHAR | UCHAR))* "'''"
[26]STRING_LITERAL_LONG_QUOTE::='"""' (('"' | '""')? ([^"\] | ECHAR | UCHAR))* '"""'
[27]UCHAR::='\u' HEX HEX HEX HEX | '\U' HEX HEX HEX HEX HEX HEX HEX HEX
[159s]ECHAR::='\' [tbnrf"'\]
[160s]NIL::='(' WS* ')'
[161s]WS::=#x20 | #x9 | #xD | #xA
[162s]ANON::='[' WS* ']'
[163s]PN_CHARS_BASE::=[A-Z] | [a-z] | [#00C0-#00D6] | [#00D8-#00F6] | [#00F8-#02FF] | [#0370-#037D] | [#037F-#1FFF] | [#200C-#200D] | [#2070-#218F] | [#2C00-#2FEF] | [#3001-#D7FF] | [#F900-#FDCF] | [#FDF0-#FFFD] | [#10000-#EFFFF]
[164s]PN_CHARS_U::=PN_CHARS_BASE | '_'
[166s]PN_CHARS::=PN_CHARS_U | '-' | [0-9] | #00B7 | [#0300-#036F] | [#203F-#2040]
[167s]PN_PREFIX::=PN_CHARS_BASE ((PN_CHARS | '.')* PN_CHARS)?
[168s]PN_LOCAL::=(PN_CHARS_U | ':' | [0-9] | PLX) ((PN_CHARS | '.' | ':' | PLX)* (PN_CHARS | ':' | PLX))?
[169s]PLX::=PERCENT | PN_LOCAL_ESC
[170s]PERCENT::='%' HEX HEX
[171s]HEX::=[0-9] | [A-F] | [a-f]
[172s]PN_LOCAL_ESC::='\' ('_' | '~' | '.' | '-' | '!' | '$' | '&' | "'" | '(' | ')' | '*' | '+' | ',' | ';' | '=' | '/' | '?' | '#' | '@' | '%')
+
+ + +
+
+
+ + +

5. Parsing

+

The RDF Concepts and Abstract Syntax [RDF11-CONCEPTS] + specification defines three types of RDF + Term: + + IRIs, + literals and + blank nodes. + Literals are composed of a lexical form and an optional language tag [BCP47] or datatype IRI. + An extra type, prefix, is used during parsing to map string identifiers to namespace IRIs. + + This section maps a string conforming to the grammar in section 4.5 Grammar to a set of triples by mapping strings matching productions and lexical tokens to RDF terms or their components (e.g. language tags, lexical forms of literals). Grammar productions change the parser state and emit triples.

+
+

5.1 Parser State

+

Parsing TriG requires a state of six items:

+ +
    +
  • IRI baseURI — When the base production is reached, the second rule argument, IRIREF, is the base URI used for relative IRI resolution.
    • + +
  • Map[prefix -> IRI] namespaces — The second and third rule arguments (PNAME_NS and IRIREF) in the prefixID production assign a namespace name (IRIREF) for the prefix (PNAME_NS). Outside of a prefixID production, any PNAME_NS is substituted with the namespace. Note that the prefix may be an empty string, per the PNAME_NS, production: (PN_PREFIX)? ":".
    • + +
  • Map[string -> blank node] bnodeLabels — A mapping from string to blank node.
    • +
  • RDF_Term curSubject — The curSubject is bound to the subject production.
    • + +
  • RDF_Term curPredicate — The curPredicate is bound to the verb production. If token matched was "a", curPredicate is bound to the IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#type.
    • + +
  • RDF_Term curGraph — + The curGraph is bound to + the label of the graph that is the destination of triples + produced in parsing. When undefined, triples are destined + for the default graph. +
    • +
+
+
+

5.2 RDF Term Constructors

+ +

This table maps productions and lexical tokens to RDF terms or components of RDF terms listed in section 5. Parsing:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
production type procedure
IRIREF IRI The characters between "<" and ">" are taken, with the numeric escape sequences unescaped, to form the unicode string of the IRI. Relative IRI resolution is performed per section 4.3 IRI References.
PNAME_NS prefix When used in a prefixID or sparqlPrefix production, the prefix is the potentially empty unicode string matching the first argument of the rule is a key into the namespaces map.
IRI When used in a PrefixedName production, the iri is the value in the namespaces map corresponding to the first argument of the rule.
PNAME_LN IRI A potentially empty prefix is identified by the first sequence, PNAME_NS. The namespaces map MUST have a corresponding namespace. The unicode string of the IRI is formed by unescaping the reserved characters in the second argument, PN_LOCAL, and concatenating this onto the namespace.
STRING_LITERAL_SINGLE_QUOTE lexical formThe characters between the outermost "'"s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_QUOTE lexical formThe characters between the outermost '"'s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_LONG_SINGLE_QUOTE lexical formThe characters between the outermost "'''"s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_LONG_QUOTE lexical formThe characters between the outermost '"""'s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
LANGTAG language tagThe characters following the @ form the unicode string of the language tag.
RDFLiteral literal The literal has a lexical form of the first rule argument, String, and either a language tag of LANGTAG or a datatype IRI of iri, depending on which rule matched the input. If the LANGTAG rule matched, the datatype is rdf:langString and the language tag is LANGTAG. If neither a language tag nor a datatype IRI is provided, the literal has a datatype of xsd:string.
INTEGER literal The literal has a lexical form of the input string, and a datatype of xsd:integer.
DECIMAL literal The literal has a lexical form of the input string, and a datatype of xsd:decimal.
DOUBLE literal The literal has a lexical form of the input string, and a datatype of xsd:double.
BooleanLiteral literal The literal has a lexical form of the true or false, depending on which matched the input, and a datatype of xsd:boolean.
BLANK_NODE_LABEL blank node The string matching the second argument, PN_LOCAL, is a key in bnodeLabels. If there is no corresponding blank node in the map, one is allocated.
ANON blank node A blank node is generated.
blankNodePropertyList blank node A blank node is generated. Note the rules for blankNodePropertyList in the next section.
collection blank node For non-empty lists, a blank node is generated. Note the rules for collection in the next section.
IRI For empty lists, the resulting IRI is rdf:nil. Note the rules for collection in the next section.
+ +
+
+

5.3 RDF Triples Construction

+

+ A TriG document defines an RDF Dataset composed of one default graph and zero or + more named graphs. Each graph is composed of a set of + RDF triples. +

+ +
+

5.3.1 Output Graph

+

The state curGraph is + initially unset. It records the label of the graph for + triples produced during parsing. If undefined, the default + graph is used.

+ +

The rule + labelOrSubject + sets both curGraph + and curSubject + (only one of these will be used). +

+ +

The following grammar production clauses set + curGraph to be undefined, indicating the default + graph: +

+
    +
  • + The grammar production clause wrappedGraph in rule block. +
    • +
  • + The grammar production in rule + triples2. +
    • +
+ +

+ The grammar production + labelOrSubject predicateObjectList '.' + unsets + curGraph + before handling predicateObjectLists + in rule triplesOrGraph. +

+ +
+
+

5.3.2 Triple Output

+

+ Each RDF triple produced is added to curGraph, + or the default graph if curGraph + is not set at that + point in the parsing process. +

+

+ The subject + production sets the curSubject. + The verb + production sets the curPredicate. +

+

Triples are produced at the following points in the + parsing process and each RDF triple produced is + added to the graph identified + by curGraph. +

+
+
5.3.2.1 Triple Production
+

+ Each object + N in the document produces an RDF triple: + curSubject + curPredicate N. +

+
+
+
5.3.2.2 Property Lists
+

+ Beginning the blankNodePropertyList production records the curSubject and curPredicate, and sets curSubject to a novel blank node B. + Finishing the blankNodePropertyList production restores curSubject and curPredicate. + The node produced by matching blankNodePropertyList is the blank node B. +

+
+
+
5.3.2.3 Collections
+

+ Beginning the collection production records the curSubject and curPredicate. + Each object in the collection production has a curSubject set to a novel blank node B and a curPredicate set to rdf:first. + For each object objectn after the first produces a triple:objectn-1 rdf:rest objectn . + Finishing the collection production creates an additional triple curSubject rdf:rest rdf:nil . and restores curSubject and curPredicate + The node produced by matching collection is the first blank node B for non-empty lists and rdf:nil for empty lists. +

+
+
+
+
+ + +
+ + +

6. Acknowledgements

This section is non-normative.

+

The editors gratefully acknowledge the work of Chris Bizer and + Richard Cyganiak in creating the original TriG specification. + Valuable contributions to this version were made by Gregg Kellogg, Eric + Prud'hommeaux and Sandro Hawke.

+

The document was improved through the review process by the wider community.

+
+ + + +
+ + +

A. Differences from Previous TriG

This section is non-normative.

+

This section describes the main differences between TriG, as + defined in this document, and earlier forms. +

    +
  • Syntax is aligned to the + Turtle [TURTLE] recommendation + for RDF terms.
    • +
  • Graph labels can be blank nodes.
    • +
  • The default graph, or sections of the default graph, do not + need to be enclosed in { ... }.
    • +
  • No support for optional = graph naming operator + or optional "." after each graph.
    • +
  • Graph labels do not have to be unique within a TriG + document. Reusing a graph label causes all the triples + for that graph to be included in the resulting graph. + Sections with the same label are combined by set union.
    • +
  • Keywords BASE, + PREFIX as in [TURTLE].
    • +
  • The optional GRAPH keyword is allowed to aid + SPARQL alignment. +
+
+
+ + +

B. Media Type Registration

+
+
Contact:
+
Eric Prud'hommeaux
+
See also:
+ +
How to Register a Media Type for a W3C Specification
+
Internet Media Type registration, consistency of use
TAG Finding 3 June 2002 (Revised 4 September 2002)
+
+

The Internet Media Type / MIME Type for TriG is "application/trig".

+

It is recommended that TriG files have the extension ".trig" (all lowercase) on all platforms.

+ +

It is recommended that TriG files stored on Macintosh HFS file systems be given a file type of "TEXT".

+

This information that follows will be submitted to the IESG for review, approval, and registration with IANA.

+
+
Type name:
+
application
+ +
Subtype name:
+
trig
+
Required parameters:
+
None
+
Optional parameters:
+
None
+ +
Encoding considerations:
+
The syntax of TriG is expressed over code points in Unicode [UNICODE]. The encoding is always UTF-8 [UTF-8].
+
Unicode code points may also be expressed using an \uXXXX (U+0000 to U+FFFF) or \UXXXXXXXX syntax (for U+10000 onwards) where X is a hexadecimal digit [0-9A-Fa-f]
+
Security considerations:
+
TriG is a general-purpose assertion language; applications may evaluate given data to infer more assertions or to dereference IRIs, invoking the security considerations of the scheme for that IRI. Note in particular, the privacy issues in [RFC3023] section 10 for HTTP IRIs. Data obtained from an inaccurate or malicious data source may lead to inaccurate or misleading conclusions, as well as the dereferencing of unintended IRIs. Care must be taken to align the trust in consulted resources with the sensitivity of the intended use of the data; inferences of potential medical treatments would likely require different trust than inferences for trip planning.
+ +
TriG is used to express arbitrary application data; security considerations will vary by domain of use. Security tools and protocols applicable to text (e.g. PGP encryption, MD5 sum validation, password-protected compression) may also be used on TriG documents. Security/privacy protocols must be imposed which reflect the sensitivity of the embedded information.
+
TriG can express data which is presented to the user, for example, RDF Schema labels. Application rendering strings retrieved from untrusted TriG documents must ensure that malignant strings may not be used to mislead the reader. The security considerations in the media type registration for XML ([RFC3023] section 10) provide additional guidance around the expression of arbitrary data and markup.
+
TriG uses IRIs as term identifiers. Applications interpreting data expressed in TriG should address the security issues of + Internationalized Resource Identifiers (IRIs) [RFC3987] Section 8, as well as + Uniform Resource Identifier (URI): Generic Syntax [RFC3986] Section 7.
+ +
Multiple IRIs may have the same appearance. Characters in different scripts may + look similar (a Cyrillic "о" may appear similar to a Latin "o"). A character followed + by combining characters may have the same visual representation as another character + (LATIN SMALL LETTER E followed by COMBINING ACUTE ACCENT has the same visual representation + as LATIN SMALL LETTER E WITH ACUTE). + + + + Any person or application that is writing or interpreting data in TriG must take care to use the IRI that matches the intended semantics, and avoid IRIs that make look similar. + Further information about matching of similar characters can be found + in Unicode Security Considerations [UNICODE-SECURITY] and + Internationalized Resource Identifiers (IRIs) [RFC3987], Section 8.
+ +
Interoperability considerations:
+
There are no known interoperability issues.
+
Published specification:
+
This specification.
+
Applications which use this media type:
+
No widely deployed applications are known to use this media + type. It may be used by some web services and clients consuming their data.
+
Additional information:
+
Magic number(s):
+
TriG documents may have the strings 'prefix' or 'base' (case + independent) near the beginning of the document.
+
File extension(s):
+
".trig"
+ +
Base URI:
+
The TriG base directive can change the current base URI + for relative IRIrefs in the language that are used sequentially + later in the document.
+
Macintosh file type code(s):
+
"TEXT"
+
Person & email address to contact for further information:
+ +
Eric Prud'hommeaux <eric@w3.org>
+
Intended usage:
+
COMMON
+
Restrictions on usage:
+
None
+
Author/Change controller:
+ +
The TriG specification is the product of the RDF WG. The W3C reserves change control over this specifications.
+
+
+ +
+ + +

C. Changes since the last publication of this document

+

Error + in grammar productions [24] and [25] fixed.

+
+ + +
+ +

D. References

D.1 Normative references

[BCP47]
A. Phillips; M. Davis. Tags for Identifying Languages. September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47 +
[EBNF-NOTATION]
Tim Bray; Jean Paoli; C. M. Sperberg-McQueen; Eve Maler; François Yergeau. EBNF Notation 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/REC-xml/#sec-notation +
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-concepts/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3023]
M. Murata; S. St.Laurent; D. Kohn. XML Media Types (RFC 3023). January 2001. RFC. URL: http://www.ietf.org/rfc/rfc3023.txt +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt +
[TURTLE]
Eric Prud'hommeaux, Gavin Carothers. RDF 1.1 Turtle: Terse RDF Triple Language. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-turtle-20140225/. The latest edition is available at http://www.w3.org/TR/turtle/ +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[UTF-8]
F. Yergeau. UTF-8, a transformation format of ISO 10646. IETF RFC 3629. November 2003. URL: http://www.ietf.org/rfc/rfc3629.txt +

D.2 Informative references

[SPARQL11-QUERY]
Steven Harris; Andy Seaborne. SPARQL 1.1 Query Language. 21 March 2013. W3C Recommendation. URL: http://www.w3.org/TR/sparql11-query/ +
[UNICODE-SECURITY]
Mark Davis; Michel Suignard. Unicode Security Considerations. URL: http://www.unicode.org/reports/tr36/ +
\ No newline at end of file diff --git a/docs/standards/references/turtle.html b/docs/standards/references/turtle.html new file mode 100644 index 0000000..827dc00 --- /dev/null +++ b/docs/standards/references/turtle.html @@ -0,0 +1,1950 @@ + + + + RDF 1.1 Turtle + + + + + + + + + + + + + +

Abstract

+

The Resource Description Framework + (RDF) is a + general-purpose language for representing information in the Web.

+ +

This document defines a textual syntax for RDF called Turtle + that allows an RDF graph to be completely written in a compact and + natural text form, with abbreviations for common usage patterns and + datatypes. Turtle provides levels of compatibility with the + N-Triples [N-TRIPLES] + format as well as the triple pattern syntax of the + SPARQL + W3C Recommendation. +

+

Status of This Document

+ + + +

+ This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/. +

+ +

This document is a part of the RDF 1.1 document suite. The + document defines Turtle, the Terse RDF Triple Language, a concrete + syntax for RDF [RDF11-CONCEPTS].

+ +

+ This document was published by the RDF Working Group as a Recommendation. + + + If you wish to make comments regarding this document, please send them to + public-rdf-comments@w3.org + (subscribe, + archives). + + + + + All comments are welcome. + +

+ +

+ Please see the Working Group's implementation + report. +

+ + + +

+ This document has been reviewed by W3C Members, by software developers, and by other W3C + groups and interested parties, and is endorsed by the Director as a W3C Recommendation. + It is a stable document and may be used as reference material or cited from another + document. W3C's role in making the Recommendation is to draw attention to the + specification and to promote its widespread deployment. This enhances the functionality + and interoperability of the Web. +

+ + +

+ + This document was produced by a group operating under the + 5 February 2004 W3C Patent + Policy. + + + + + W3C maintains a public list of any patent + disclosures + + made in connection with the deliverables of the group; that page also includes + instructions for disclosing a patent. An individual who has actual knowledge of a patent + which the individual believes contains + Essential + Claim(s) must disclose the information in accordance with + section + 6 of the W3C Patent Policy. + + +

+ + + + +

Table of Contents

+ + + +
+ + +

1. Introduction

This section is non-normative.

+ +

+ This document defines Turtle, the Terse RDF + Triple Language, a concrete syntax for + RDF [RDF11-CONCEPTS]. +

+ +

+ A Turtle document is a textual representations of an RDF graph. The following Turtle document describes the relationship between Green Goblin and Spiderman. +

+
Example 1
@base <http://example.org/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix rel: <http://www.perceive.net/schemas/relationship/> .
+
+<#green-goblin>
+    rel:enemyOf <#spiderman> ;
+    a foaf:Person ;    # in the context of the Marvel universe
+    foaf:name "Green Goblin" .
+
+<#spiderman>
+    rel:enemyOf <#green-goblin> ;
+    a foaf:Person ;
+    foaf:name "Spiderman", "Человек-паук"@ru .
+

+ This example introduces many of features of the Turtle language: +@base and Relative IRIs, +@prefix and prefixed names, +predicate lists separated by ';', +object lists separated by ',', +the token a, +and literals. +

+ +

+ The Turtle grammar for triples + is a subset of the SPARQL + 1.1 Query Language [SPARQL11-QUERY] grammar for TriplesBlock. + The two grammars share production and terminal names where possible. +

+ +

+ The construction of an RDF graph from a Turtle document is defined in Turtle Grammar and Parsing. +

+ +
+
+ + +

2. Turtle Language

This section is non-normative.

+

A Turtle document allows writing down an RDF graph in a compact textual form. An RDF graph is made up of triples consisting of a subject, predicate and object.

+

Comments may be given after a '#' that is not part of another lexical token and continue to the end of the line.

+
+

2.1 Simple Triples

+

The simplest triple statement is a sequence of (subject, predicate, object) terms, separated by whitespace and terminated by '.' after each triple.

+
Example 2
<http://example.org/#spiderman> <http://www.perceive.net/schemas/relationship/enemyOf> <http://example.org/#green-goblin> .
+
+
+
+

2.2 Predicate Lists

+

Often the same subject will be referenced by a number of predicates. The predicateObjectList production matches a series of predicates and objects, separated by ';', following a subject. + This expresses a series of RDF Triples with that subject and each predicate and object allocated to one triple. + Thus, the ';' symbol is used to repeat the subject of triples that vary only in predicate and object RDF terms.

+

These two examples are equivalent ways of writing the triples about Spiderman.

+
Example 3
<http://example.org/#spiderman> <http://www.perceive.net/schemas/relationship/enemyOf> <http://example.org/#green-goblin> ;
+				<http://xmlns.com/foaf/0.1/name> "Spiderman" .
+
+
Example 4
<http://example.org/#spiderman> <http://www.perceive.net/schemas/relationship/enemyOf> <http://example.org/#green-goblin> .
+<http://example.org/#spiderman> <http://xmlns.com/foaf/0.1/name> "Spiderman" .
+
+
+
+

2.3 Object Lists

+

+ As with predicates often objects are repeated with the same subject and predicate. The objectList production matches a series of objects separated by ',' following a predicate. + This expresses a series of RDF Triples with the corresponding subject and predicate and each object allocated to one triple. + Thus, the ',' symbol is used to repeat the subject and predicate of triples that only differ in the object RDF term.

+

These two examples are equivalent ways of writing Spiderman's name in two languages.

+

Example 5
<http://example.org/#spiderman> <http://xmlns.com/foaf/0.1/name> "Spiderman", "Человек-паук"@ru .
+
+
Example 6
<http://example.org/#spiderman> <http://xmlns.com/foaf/0.1/name> "Spiderman" .
+<http://example.org/#spiderman> <http://xmlns.com/foaf/0.1/name> "Человек-паук"@ru .
+
+ +
+ +

+ There are three types of RDF Term defined in RDF Concepts: + IRIs (Internationalized Resource Identifiers), + literals and + blank nodes. Turtle provides a number + of ways of writing each. +

+ +
+

2.4 IRIs

+ +

+ IRIs may be written as relative or absolute IRIs or prefixed names. + Relative and absolute IRIs are enclosed in '<' and '>' and may contain numeric escape sequences (described below). For example <http://example.org/#green-goblin>. +

+

Relative IRIs like <#green-goblin> are resolved relative to the current base IRI. A new base IRI can be defined using the '@base' or 'BASE' directive. Specifics of this operation are defined in section 6.3 IRI References

+

+ The token 'a' in the predicate position of a Turtle triple represents the IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#type . +

+ +

+ A prefixed name is a prefix label and a local part, separated by a colon ":". + A prefixed name is turned into an IRI by concatenating the IRI associated with the prefix and the local part. The '@prefix' or 'PREFIX' directive associates a prefix label with an IRI. + Subsequent '@prefix' or 'PREFIX' directives may re-map the same prefix label.

+ +
Note
+

+ The Turtle language originally permitted only the syntax including the '@' character for writing prefix and base directives. + The case-insensitive 'PREFIX' and 'BASE' forms were added to align Turtle's syntax with that of SPARQL. + It is advisable to serialize RDF using the '@prefix' and '@base' forms until RDF 1.1 Turtle parsers are widely deployed. +

+
+ +

+ To write http://www.perceive.net/schemas/relationship/enemyOf using a prefixed name:

+
    +
  1. Define a prefix label for the vocabulary IRI http://www.perceive.net/schemas/relationship/ as somePrefix +
  2. Then write somePrefix:enemyOf which is equivalent to writing <http://www.perceive.net/schemas/relationship/enemyOf>
    3. +
+ +

+ This can be written using either the original Turtle syntax for prefix declarations:

+ +
Example 7
@prefix somePrefix: <http://www.perceive.net/schemas/relationship/> .
+
+<http://example.org/#green-goblin> somePrefix:enemyOf <http://example.org/#spiderman> .
+
+

+ or SPARQL's syntax for prefix declarations:

+
Example 8
PREFIX somePrefix: <http://www.perceive.net/schemas/relationship/>
+
+<http://example.org/#green-goblin> somePrefix:enemyOf <http://example.org/#spiderman> .
+
+ + +
Note
+

+ Prefixed names are a superset of XML QNames. + They differ in that the local part of prefixed names may include: +

+ +
+ +

The following Turtle document contains examples of all the different ways of writing IRIs in Turtle.

+ +
Example 9
# A triple with all absolute IRIs
+<http://one.example/subject1> <http://one.example/predicate1> <http://one.example/object1> .
+
+@base <http://one.example/> .
+<subject2> <predicate2> <object2> .     # relative IRIs, e.g. http://one.example/subject2
+
+BASE <http://one.example/>
+<subject2> <predicate2> <object2> .     # relative IRIs, e.g. http://one.example/subject2
+
+@prefix p: <http://two.example/> .
+p:subject3 p:predicate3 p:object3 .     # prefixed name, e.g. http://two.example/subject3
+
+PREFIX p: <http://two.example/>
+p:subject3 p:predicate3 p:object3 .     # prefixed name, e.g. http://two.example/subject3
+
+@prefix p: <path/> .                    # prefix p: now stands for http://one.example/path/
+p:subject4 p:predicate4 p:object4 .     # prefixed name, e.g. http://one.example/path/subject4
+
+@prefix : <http://another.example/> .    # empty prefix
+:subject5 :predicate5 :object5 .        # prefixed name, e.g. http://another.example/subject5
+
+:subject6 a :subject7 .                 # same as :subject6 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> :subject7 .
+
+<http://伝言.example/?user=أكرم&amp;channel=R%26D> a :subject8 . # a multi-script subject IRI .
+
+
Note
+

The '@prefix' and '@base' directives require a trailing '.' after the IRI, the equalivent 'PREFIX' and 'BASE' must not have a trailing '.' after the IRI part of the directive. +

+
+ + + + +
+

2.5 RDF Literals

+ +

Literals are used to identify values such as strings, numbers, dates.

+ +
Example 10
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+<http://example.org/#green-goblin> foaf:name "Green Goblin" .
+
+<http://example.org/#spiderman> foaf:name "Spiderman" .
+ + +
+

2.5.1 Quoted Literals

+ +

+ Quoted Literals (Grammar production RDFLiteral) have a lexical form followed by a language tag, a datatype IRI, or neither. + The representation of the lexical form consists of an initial delimiter, e.g. " (U+0022), a sequence of permitted characters or numeric escape sequence or string escape sequence, and a final delimiter. + The corresponding RDF lexical form is the characters between the delimiters, after processing any escape sequences. + If present, the language tag is preceded by a '@' (U+0040). + If there is no language tag, there may be a datatype IRI, preceeded by '^^' (U+005E U+005E). The datatype IRI in Turtle may be written using either an absolute IRI, a relative IRI, or prefixed name. If there is no datatype IRI and no language tag, the datatype is xsd:string. +

+

'\' (U+005C) may not appear in any quoted literal except as part of an escape sequence. Other restrictions depend on the delimiter:

+
    +
  • Literals delimited by ' (U+0027), may not contain the characters ', LF (U+000A), or CR (U+000D). +
  • Literals delimited by ", may not contain the characters ", LF, or CR. +
  • Literals delimited by ''' may not contain the sequence of characters '''. +
  • Literals delimited by """ may not contain the sequence of characters """. +
+
Example 11
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix show: <http://example.org/vocab/show/> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+show:218 rdfs:label "That Seventies Show"^^xsd:string .            # literal with XML Schema string datatype
+show:218 rdfs:label "That Seventies Show"^^<http://www.w3.org/2001/XMLSchema#string> . # same as above
+show:218 rdfs:label "That Seventies Show" .                                            # same again
+show:218 show:localName "That Seventies Show"@en .                 # literal with a language tag
+show:218 show:localName 'Cette Série des Années Soixante-dix'@fr . # literal delimited by single quote
+show:218 show:localName "Cette Série des Années Septante"@fr-be .  # literal with a region subtag
+show:218 show:blurb '''This is a multi-line                        # literal with embedded new lines and quotes
+literal with many quotes (""""")
+and up to two sequential apostrophes ('').''' .
+
+
+
+

2.5.2 Numbers

+

Numbers can be written like other literals with lexical form and datatype (e.g. "-5.0"^^xsd:decimal). Turtle has a shorthand syntax for writing integer values, arbitrary precision decimal values, and double precision floating point values.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Data TypeAbbreviatedLexicalDescription
xsd:integer-5"-5"^^xsd:integerInteger values may be written as an optional sign and a series of digits. Integers match the regular expression "[+-]?[0-9]+".
xsd:decimal-5.0"-5.0"^^xsd:decimalArbitrary-precision decimals may be written as an optional sign, zero or more digits, a decimal point and one or more digits. Decimals match the regular expression "[+-]?[0-9]*\.[0-9]+".
xsd:double4.2E9"4.2E9"^^xsd:doubleDouble-precision floating point values may be written as an optionally signed mantissa with an optional decimal point, the letter "e" or "E", and an optionally signed integer exponent. The exponent matches the regular expression "[+-]?[0-9]+" and the mantissa one of these regular expressions: "[+-]?[0-9]+\.[0-9]+", "[+-]?\.[0-9]+" or "[+-]?[0-9]".
+ + + + +
Example 12
@prefix : <http://example.org/elements> .                                                                              
+<http://en.wikipedia.org/wiki/Helium>                                                                                  
+    :atomicNumber 2 ;               # xsd:integer                                                                      
+    :atomicMass 4.002602 ;          # xsd:decimal                                                                      
+    :specificGravity 1.663E-4 .     # xsd:double                                                                       
+
+
+
+

2.5.3 Booleans

+

Boolean values may be written as either 'true' or 'false' (case-sensitive) and represent RDF literals with the datatype xsd:boolean.

+
Example 13
@prefix : <http://example.org/stats> .
+<http://somecountry.example/census2007>
+    :isLandlocked false .           # xsd:boolean
+ +
+
+ +
+

2.6 RDF Blank Nodes

+

+ RDF blank nodes in Turtle are expressed as _: followed by a blank node label which is a series of name characters. + The characters in the label are built upon PN_CHARS_BASE, liberalized as follows: +

+
    +
  • The characters _ and digits may appear anywhere in a blank node label.
    • +
  • The character . may appear anywhere except the first or last character.
    • +
  • The characters -, U+00B7, U+0300 to U+036F and U+203F to U+2040 are permitted anywhere except the first character.
    • +
+

+ A fresh RDF blank node is allocated for each unique blank node label in a document. + Repeated use of the same blank node label identifies the same RDF blank node. +

+
Example 14
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+_:alice foaf:knows _:bob .
+_:bob foaf:knows _:alice .
+
+
+
+

2.7 Nesting Unlabeled Blank Nodes in Turtle

+

+ In Turtle, fresh RDF blank nodes are also allocated when matching the production blankNodePropertyList and the terminal ANON. + Both of these may appear in the subject or object position of a triple (see the Turtle Grammar). + That subject or object is a fresh RDF blank node. + This blank node also serves as the subject of the triples produced by matching the predicateObjectList production embedded in a blankNodePropertyList. + The generation of these triples is described in Predicate Lists. + Blank nodes are also allocated for collections described below. +

+
Example 15
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+# Someone knows someone else, who has the name "Bob".
+[] foaf:knows [ foaf:name "Bob" ] .
+
+ +

+ The Turtle grammar allows blankNodePropertyLists to be nested. + In this case, each inner [ establishes a new subject blank node which reverts to the outer node at the ], and serves as the current subject for predicate object lists. +

+

+ The use of predicateObjectList within a blankNodePropertyList is a common idiom for representing a series of properties of a node. +

+
+

Abbreviated:

+
Example 16
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+[ foaf:name "Alice" ] foaf:knows [
+    foaf:name "Bob" ;
+    foaf:knows [
+        foaf:name "Eve" ] ;
+    foaf:mbox <bob@example.com> ] .
+
+
+
+

Corresponding simple triples:

+
Example 17

+_:a <http://xmlns.com/foaf/0.1/name> "Alice" .
+_:a <http://xmlns.com/foaf/0.1/knows> _:b .
+_:b <http://xmlns.com/foaf/0.1/name> "Bob" .
+_:b <http://xmlns.com/foaf/0.1/knows> _:c .
+_:c <http://xmlns.com/foaf/0.1/name> "Eve" .
+_:b <http://xmlns.com/foaf/0.1/mbox> <bob@example.com> .
+
+
+
+ +
+
+

2.8 Collections

+ +

+ RDF provides a Collection [RDF11-MT] structure for lists of RDF nodes. + The Turtle syntax for Collections is a possibly empty list of RDF terms enclosed by (). + This collection represents an rdf:first/rdf:rest list structure with the sequence of objects of the rdf:first statements being the order of the terms enclosed by (). +

+ +

+ The (…) syntax MUST appear in the subject or object position of a triple (see the Turtle Grammar). + The blank node at the head of the list is the subject or object of the containing triple. +

+ +
Example 18

+@prefix : <http://example.org/foo> .
+# the object of this triple is the RDF collection blank node
+:subject :predicate ( :a :b :c ) .
+
+# an empty collection value - rdf:nil
+:subject :predicate2 () .
+
+ +
+
+
+ + +

3. Examples

This section is non-normative.

+ +

This example is a Turtle translation of + example 7 + in the + RDF/XML Syntax specification + (example1.ttl): +

+ +
Example 19
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix dc: <http://purl.org/dc/elements/1.1/> .
+@prefix ex: <http://example.org/stuff/1.0/> .
+
+<http://www.w3.org/TR/rdf-syntax-grammar>
+  dc:title "RDF/XML Syntax Specification (Revised)" ;
+  ex:editor [
+    ex:fullname "Dave Beckett";
+    ex:homePage <http://purl.org/net/dajobe/>
+  ] .
+ + +

An example of an RDF collection of two literals.

+
Example 20

+PREFIX : <http://example.org/stuff/1.0/>
+:a :b ( "apple" "banana" ) .
+
+

which is short for (example2.ttl):

+ +
Example 21
@prefix : <http://example.org/stuff/1.0/> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+:a :b
+  [ rdf:first "apple";
+    rdf:rest [ rdf:first "banana";
+               rdf:rest rdf:nil ]
+  ] .
+ +

An example of two identical triples containing literal objects + containing newlines, written in plain and long literal forms. + The line breaks in this example are LINE FEED characters (U+000A). + (example3.ttl):

+ +
Example 22
@prefix : <http://example.org/stuff/1.0/> .
+
+:a :b "The first line\nThe second line\n  more" .
+
+:a :b """The first line
+The second line
+  more""" .
+ +

As indicated by the grammar, a collection can be either a subject or an object. This subject or object will be the novel blank node for the first object, if the collection has one or more objects, or rdf:nil if the collection is empty.

+ +

For example,

+ +
Example 23
@prefix : <http://example.org/stuff/1.0/> .
+(1 2.0 3E1) :p "w" .
+ +

is syntactic sugar for (noting that the blank nodes b0, b1 and b2 do not occur anywhere else in the RDF graph):

+ +
Example 24
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+    _:b0  rdf:first  1 ;
+          rdf:rest   _:b1 .
+    _:b1  rdf:first  2.0 ;
+          rdf:rest   _:b2 .
+    _:b2  rdf:first  3E1 ;
+          rdf:rest   rdf:nil .
+    _:b0  :p         "w" .
+ +

RDF collections can be nested and can involve other syntactic forms:

+ +
Example 25
PREFIX : <http://example.org/stuff/1.0/>
+(1 [:p :q] ( 2 ) ) :p2 :q2 .
+ +

is syntactic sugar for:

Example 26
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+    _:b0  rdf:first  1 ;
+          rdf:rest   _:b1 .
+    _:b1  rdf:first  _:b2 .
+    _:b2  :p         :q .
+    _:b1  rdf:rest   _:b3 .
+    _:b3  rdf:first  _:b4 .
+    _:b4  rdf:first  2 ;
+          rdf:rest   rdf:nil .
+    _:b3  rdf:rest   rdf:nil .
+
+ +
+ + +

4. Turtle compared to SPARQL

This section is non-normative.

+ +

The SPARQL 1.1 + Query LanguageF (SPARQL) [SPARQL11-QUERY] uses a Turtle style syntax for its TriplesBlock production. + This production differs from the Turtle language in that: +

+ +
    +
  1. SPARQL permits RDF Literals as the subject of RDF triples.
    2. + +
  2. SPARQL permits variables (?name or $name) in any part of the triple of the form.
    3. +
  3. Turtle allows prefix and base declarations anywhere outside of a triple. In SPARQL, they are only allowed in the Prologue (at the start of the SPARQL query).
    4. +
  4. SPARQL uses case insensitive keywords, except for 'a'. Turtle's @prefix and @base declarations are case sensitive, the SPARQL dervied PREFIX and BASE are case insensitive.
    5. +
  5. 'true' and 'false' are case insensitive in SPARQL and case sensitive in Turtle. TrUe is not a valid boolean value in Turtle.
    6. + +
+ +

For further information see the + Syntax for IRIs + and SPARQL Grammar + sections of the SPARQL query document [SPARQL11-QUERY]. +

+
+
+ +

5. Conformance

+

+ As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, + and notes in this specification are non-normative. Everything else in this specification is + normative. +

+

+ The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, + and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. +

+ +

This specification defines conformance criteria for:

+
    +
  • Turtle documents +
  • Turtle parsers +
+

A conforming Turtle document is a Unicode string that conforms to the grammar and additional constraints defined in section 6. Turtle Grammar, starting with the turtleDoc production. A Turtle document serializes an RDF Graph.

+ +

A conforming Turtle parser is a system capable of reading Turtle documents on behalf of an application. It makes the serialized RDF dataset, as defined in section 7. Parsing, available to the application, usually through some form of API.

+ +

The IRI that identifies the Turtle language is: http://www.w3.org/ns/formats/Turtle

+ +
Note

This specification does not define how Turtle parsers handle non-conforming input documents.

+
+

5.1 Media Type and Content Encoding

+ +

The media type of Turtle is text/turtle. + The content encoding of Turtle content is always UTF-8. Charset + parameters on the mime type are required until such time as the + text/ media type tree permits UTF-8 to be sent without a + charset parameter. See section B. Internet Media Type, File Extension and Macintosh File Type for the media type + registration form. +

+
+
+ +
+ + +

6. Turtle Grammar

+ +

A Turtle document is a + Unicode[UNICODE] + character string encoded in UTF-8. + Unicode characters only in the range U+0000 to U+10FFFF inclusive are + allowed. +

+
+

6.1 White Space

+

White space (production WS) is used to separate two terminals which would otherwise be (mis-)recognized as one terminal. Rule names below in capitals indicate where white space is significant; these form a possible choice of terminals for constructing a Turtle parser.

+ +

White space is significant in the production String.

+
+
+

6.2 Comments

+ +

Comments in Turtle take the form of '#', outside an + IRIREF or String, + and continue to the end of line (marked by characters U+000D or U+000A) + or end of file if there is no end of line after the comment + marker. Comments are treated as white space. + +

+
+
+

6.3 IRI References

+

+ Relative IRIs are resolved with base IRIs as per Uniform Resource Identifier (URI): Generic Syntax [RFC3986] using only the basic algorithm in section 5.2. + Neither Syntax-Based Normalization nor Scheme-Based Normalization (described in sections 6.2.2 and 6.2.3 of RFC3986) are performed. + Characters additionally allowed in IRI references are treated in the same way that unreserved characters are treated in URI references, per section 6.5 of Internationalized Resource Identifiers (IRIs) [RFC3987]. +

+

+ The @base or BASE directive defines the Base IRI used to resolve relative IRIs per RFC3986 section 5.1.1, "Base URI Embedded in Content". + Section 5.1.2, "Base URI from the Encapsulating Entity" defines how the In-Scope Base IRI may come from an encapsulating document, such as a SOAP envelope with an xml:base directive or a mime multipart document with a Content-Location header. + The "Retrieval URI" identified in 5.1.3, Base "URI from the Retrieval URI", is the URL from which a particular Turtle document was retrieved. + If none of the above specifies the Base URI, the default Base URI (section 5.1.4, "Default Base URI") is used. + Each @base or BASE directive sets a new In-Scope Base URI, relative to the previous one. +

+
+ +
+

6.4 Escape Sequences

+ +

+ There are three forms of escapes used in turtle documents: +

+ +
    +
  • +

    + numeric escape sequences represent Unicode code points: +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    Escape sequenceUnicode code point
    '\u' hex hex hex hexA Unicode character in the range U+0000 to U+FFFF inclusive + corresponding to the value encoded by the four hexadecimal digits interpreted from most significant to least significant digit.
    '\U' hex hex hex hex hex hex hex hexA Unicode character in the range U+0000 to U+10FFFF inclusive + corresponding to the value encoded by the eight hexadecimal digits interpreted from most significant to least significant digit.
    + +

    where HEX is a hexadecimal character

    +
    +

    HEX + ::= [0-9] | [A-F] | [a-f]

    + +
    +
    • + +
  • +

    + string escape sequences represent the characters traditionally escaped in string literals: +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Escape sequenceUnicode code point
    '\t'U+0009
    '\b'U+0008
    '\n'U+000A
    '\r'U+000D
    '\f'U+000C
    '\"'U+0022
    '\''U+0027
    '\\'U+005C
    +
    • + +
  • +

    + reserved character escape sequences consist of a '\' followed by one of ~.-!$&'()*+,;=/?#@%_ and represent the character to the right of the '\'. +

    +
    • + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Context where each kind of escape sequence can be used
numeric
escapes		string
escapes		reserved character
escapes
IRIs, used as RDF terms or as in @prefix, PREFIX, @base, or BASE declarationsyesnono
local namesnonoyes
Stringsyesyesno
+
Note

%-encoded sequences are in the character range for IRIs and are explicitly allowed in local names. These appear as a '%' followed by two hex characters and represent that same sequence of three characters. These sequences are not decoded during processing. A term written as <http://a.example/%66oo-bar> in Turtle designates the IRI http://a.example/%66oo-bar and not IRI http://a.example/foo-bar. A term written as ex:%66oo-bar with a prefix @prefix ex: <http://a.example/> also designates the IRI http://a.example/%66oo-bar.

+ +
+
+

6.5 Grammar

+

The EBNF used here is defined in XML 1.0 + [EBNF-NOTATION]. Production labels consisting of a + number and a final 's', e.g. [60s], reference the production + with that number in the SPARQL + 1.1 Query Language grammar [SPARQL11-QUERY]. +

+ +
+

Notes:

+
    +
  1. + Keywords in single quotes ('@base', '@prefix', 'a', 'true', 'false') are case-sensitive. + Keywords in double quotes ("BASE", "PREFIX") are case-insensitive. +
    2. +
  2. + Escape sequences UCHAR and ECHAR are case sensitive. +
    3. +
  3. + When tokenizing the input and choosing grammar rules, the longest match is chosen. +
    4. +
  4. + The Turtle grammar is LL(1) and LALR(1) when the rules with uppercased names are used as terminals. +
    5. +
  5. + The entry point into the grammar is turtleDoc. +
    6. +
  6. + In signed numbers, no white space is allowed between the sign and the number. +
    7. +
  7. + The + + [162s] + ANON + ::= + '[' WS* ']' + + token allows any amount of white space and comments between []s. + The single space version is used in the grammar for clarity. +
    8. +
  8. + The strings '@prefix' and '@base' match the pattern for LANGTAG, though neither "prefix" nor "base" are registered language subtags. + This specification does not define whether a quoted literal followed by either of these tokens (e.g. "A"@base) is in the Turtle language. +
    9. +
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1]turtleDoc::=statement*
[2]statement::=directive | triples '.'
[3]directive::=prefixID | base | sparqlPrefix | sparqlBase
[4]prefixID::='@prefix' PNAME_NS IRIREF '.'
[5]base::='@base' IRIREF '.'
[5s]sparqlBase::="BASE" IRIREF
[6s]sparqlPrefix::="PREFIX" PNAME_NS IRIREF
[6]triples::=subject predicateObjectList | blankNodePropertyList predicateObjectList?
[7]predicateObjectList::=verb objectList (';' (verb objectList)?)*
[8]objectList::=object (',' object)*
[9]verb::=predicate | 'a'
[10]subject::=iri | BlankNode | collection
[11]predicate::=iri
[12]object::=iri | BlankNode | collection | blankNodePropertyList | literal
[13]literal::=RDFLiteral | NumericLiteral | BooleanLiteral
[14]blankNodePropertyList::='[' predicateObjectList ']'
[15]collection::='(' object* ')'
[16]NumericLiteral::=INTEGER | DECIMAL | DOUBLE
[128s]RDFLiteral::=String (LANGTAG | '^^' iri)?
[133s]BooleanLiteral::='true' | 'false'
[17]String::=STRING_LITERAL_QUOTE | STRING_LITERAL_SINGLE_QUOTE | STRING_LITERAL_LONG_SINGLE_QUOTE | STRING_LITERAL_LONG_QUOTE
[135s]iri::=IRIREF | PrefixedName
[136s]PrefixedName::=PNAME_LN | PNAME_NS
[137s]BlankNode::=BLANK_NODE_LABEL | ANON

Productions for terminals

[18]IRIREF::='<' ([^#x00-#x20<>"{}|^`\] | UCHAR)* '>' /* #x00=NULL #01-#x1F=control codes #x20=space */
[139s]PNAME_NS::=PN_PREFIX? ':'
[140s]PNAME_LN::=PNAME_NS PN_LOCAL
[141s]BLANK_NODE_LABEL::='_:' (PN_CHARS_U | [0-9]) ((PN_CHARS | '.')* PN_CHARS)?
[144s]LANGTAG::='@' [a-zA-Z]+ ('-' [a-zA-Z0-9]+)*
[19]INTEGER::=[+-]? [0-9]+
[20]DECIMAL::=[+-]? [0-9]* '.' [0-9]+
[21]DOUBLE::=[+-]? ([0-9]+ '.' [0-9]* EXPONENT | '.' [0-9]+ EXPONENT | [0-9]+ EXPONENT)
[154s]EXPONENT::=[eE] [+-]? [0-9]+
[22]STRING_LITERAL_QUOTE::='"' ([^#x22#x5C#xA#xD] | ECHAR | UCHAR)* '"' /* #x22=" #x5C=\ #xA=new line #xD=carriage return */
[23]STRING_LITERAL_SINGLE_QUOTE::="'" ([^#x27#x5C#xA#xD] | ECHAR | UCHAR)* "'" /* #x27=' #x5C=\ #xA=new line #xD=carriage return */
[24]STRING_LITERAL_LONG_SINGLE_QUOTE::="'''" (("'" | "''")? ([^'\] | ECHAR | UCHAR))* "'''"
[25]STRING_LITERAL_LONG_QUOTE::='"""' (('"' | '""')? ([^"\] | ECHAR | UCHAR))* '"""'
[26]UCHAR::='\u' HEX HEX HEX HEX | '\U' HEX HEX HEX HEX HEX HEX HEX HEX
[159s]ECHAR::='\' [tbnrf"'\]
[161s]WS::=#x20 | #x9 | #xD | #xA /* #x20=space #x9=character tabulation #xD=carriage return #xA=new line */
[162s]ANON::='[' WS* ']'
[163s]PN_CHARS_BASE::=[A-Z] | [a-z] | [#x00C0-#x00D6] | [#x00D8-#x00F6] | [#x00F8-#x02FF] | [#x0370-#x037D] | [#x037F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[164s]PN_CHARS_U::=PN_CHARS_BASE | '_'
[166s]PN_CHARS::=PN_CHARS_U | '-' | [0-9] | #x00B7 | [#x0300-#x036F] | [#x203F-#x2040]
[167s]PN_PREFIX::=PN_CHARS_BASE ((PN_CHARS | '.')* PN_CHARS)?
[168s]PN_LOCAL::=(PN_CHARS_U | ':' | [0-9] | PLX) ((PN_CHARS | '.' | ':' | PLX)* (PN_CHARS | ':' | PLX))?
[169s]PLX::=PERCENT | PN_LOCAL_ESC
[170s]PERCENT::='%' HEX HEX
[171s]HEX::=[0-9] | [A-F] | [a-f]
[172s]PN_LOCAL_ESC::='\' ('_' | '~' | '.' | '-' | '!' | '$' | '&' | "'" | '(' | ')' | '*' | '+' | ',' | ';' | '=' | '/' | '?' | '#' | '@' | '%')
+
+
+
+
+ + +

7. Parsing

+ +

The RDF 1.1 Concepts and Abstract Syntax specification [RDF11-CONCEPTS] defines three types of RDF Term: + + IRIs, + literals and + blank nodes. + Literals are composed of a lexical form and an optional language tag [BCP47] or datatype IRI. + An extra type, prefix, is used during parsing to map string identifiers to namespace IRIs. + + This section maps a string conforming to the grammar in section 6.5 Grammar to a set of triples by mapping strings matching productions and lexical tokens to RDF terms or their components (e.g. language tags, lexical forms of literals). Grammar productions change the parser state and emit triples.

+ +
+

7.1 Parser State

+ +

Parsing Turtle requires a state of five items:

+ +
    +
  • IRI baseURI + — When the base + production is reached, the second rule argument, + IRIREF, is the base URI used for relative + IRI resolution. + + + +
    • + +
  • Map[prefix -> IRI] namespaces — The second and third + rule arguments (PNAME_NS and + IRIREF) in the prefixID + production assign a namespace name + (IRIREF) for the prefix + (PNAME_NS). Outside of a + prefixID production, any + PNAME_NS is substituted with the + namespace. + + + + Note that the prefix may be an empty string, per the + PNAME_NS production: (PN_PREFIX)? ":". + + + +
    • + +
  • Map[string -> blank + node] bnodeLabels — A + mapping from string to blank node.
    • + +
  • RDF_Term curSubject — The curSubject is bound to the + subject + production.
    • + +
  • RDF_Term curPredicate — The curPredicate is bound to + the verb + production. If token matched was "a", + curPredicate is + bound to the IRI + http://www.w3.org/1999/02/22-rdf-syntax-ns#type. + + + +
    • + +
+
+ +
+

7.2 RDF Term Constructors

+ +

This table maps productions and lexical tokens to RDF terms or components of RDF terms listed in section 7. Parsing:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
production type procedure
IRIREF IRI The characters between "<" and ">" are taken, with the numeric escape sequences unescaped, to form the unicode string of the IRI. Relative IRI resolution is performed per Section 6.3.
PNAME_NS prefix When used in a prefixID or sparqlPrefix production, the prefix is the potentially empty unicode string matching the first argument of the rule is a key into the namespaces map.
IRI When used in a PrefixedName production, the iri is the value in the namespaces map corresponding to the first argument of the rule.
PNAME_LN IRI A potentially empty prefix is identified by the first sequence, PNAME_NS. The namespaces map MUST have a corresponding namespace. The unicode string of the IRI is formed by unescaping the reserved characters in the second argument, PN_LOCAL, and concatenating this onto the namespace.
STRING_LITERAL_SINGLE_QUOTE lexical formThe characters between the outermost "'"s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_QUOTE lexical formThe characters between the outermost '"'s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_LONG_SINGLE_QUOTE lexical formThe characters between the outermost "'''"s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
STRING_LITERAL_LONG_QUOTE lexical formThe characters between the outermost '"""'s are taken, with numeric and string escape sequences unescaped, to form the unicode string of a lexical form.
LANGTAG language tagThe characters following the @ form the unicode string of the language tag.
RDFLiteral literal The literal has a lexical form of the first rule argument, String. If the '^^' iri rule matched, the datatype is iri and the literal has no language tag. If the LANGTAG rule matched, the datatype is rdf:langString and the language tag is LANGTAG. If neither matched, the datatype is xsd:string and the literal has no language tag.
INTEGER literal The literal has a lexical form of the input string, and a datatype of xsd:integer.
DECIMAL literal The literal has a lexical form of the input string, and a datatype of xsd:decimal.
DOUBLE literal The literal has a lexical form of the input string, and a datatype of xsd:double.
BooleanLiteral literal The literal has a lexical form of the true or false, depending on which matched the input, and a datatype of xsd:boolean.
BLANK_NODE_LABEL blank node The string matching the second argument, PN_LOCAL, is a key in bnodeLabels. If there is no corresponding blank node in the map, one is allocated.
ANON blank node A blank node is generated.
blankNodePropertyList blank node A blank node is generated. Note the rules for blankNodePropertyList in the next section.
collection blank node For non-empty lists, a blank node is generated. Note the rules for collection in the next section.
IRI For empty lists, the resulting IRI is rdf:nil. Note the rules for collection in the next section.
+ +
+
+

7.3 RDF Triples Constructors

+

+ A Turtle document defines an RDF graph composed of set of RDF triples. + The subject production sets the curSubject. + The verb production sets the curPredicate. + Each object N in the document produces an RDF triple: curSubject curPredicate N . +

+ +

Property Lists:

+

+ Beginning the blankNodePropertyList production records the curSubject and curPredicate, and sets curSubject to a novel blank node B. + Finishing the blankNodePropertyList production restores curSubject and curPredicate. + The node produced by matching blankNodePropertyList is the blank node B. + +

+ +

Collections:

+

+ Beginning the collection production records the curSubject and curPredicate. + Each object in the collection production has a curSubject set to a novel blank node B and a curPredicate set to rdf:first. + For each object objectn after the first produces a triple:objectn-1 rdf:rest objectn . + Finishing the collection production creates an additional triple curSubject rdf:rest rdf:nil . and restores curSubject and curPredicate + The node produced by matching collection is the first blank node B for non-empty lists and rdf:nil for empty lists. +

+
+
+

7.4 Parsing Example

This section is non-normative.

+ +

The following informative example shows the semantic actions performed when parsing this Turtle document with an LALR(1) parser:

+
Example 27

+@prefix ericFoaf: <http://www.w3.org/People/Eric/ericP-foaf.rdf#> .
+@prefix : <http://xmlns.com/foaf/0.1/> .
+ericFoaf:ericP :givenName "Eric" ;
+              :knows <http://norman.walsh.name/knows/who/dan-brickley> ,
+                      [ :mbox <mailto:timbl@w3.org> ] ,
+                      <http://getopenid.com/amyvdh> .
+
+ +
    +
  • Map the prefix ericFoaf to the IRI http://www.w3.org/People/Eric/ericP-foaf.rdf#.
    • +
  • Map the empty prefix to the IRI http://xmlns.com/foaf/0.1/.
    • +
  • Assign curSubject the IRI http://www.w3.org/People/Eric/ericP-foaf.rdf#ericP.
    • + +
  • Assign curPredicate the IRI http://xmlns.com/foaf/0.1/givenName.
    • +
  • Emit an RDF triple: <...rdf#ericP> <.../givenName> "Eric" .
    • + +
  • Assign curPredicate the IRI http://xmlns.com/foaf/0.1/knows.
    • +
  • Emit an RDF triple: <...rdf#ericP> <.../knows> <...who/dan-brickley> .
    • + +
  • Emit an RDF triple: <...rdf#ericP> <.../knows> _:1 .
    • +
  • Save curSubject and reassign to the blank node _:1.
    • + +
  • Save curPredicate.
    • +
  • Assign curPredicate the IRI http://xmlns.com/foaf/0.1/mbox.
    • +
  • Emit an RDF triple: _:1 <.../mbox> <mailto:timbl@w3.org> .
    • + +
  • Restore curSubject and curPredicate to their saved values (<...rdf#ericP>, <.../knows>).
    • +
  • Emit an RDF triple: <...rdf#ericP> <.../knows> <http://getopenid.com/amyvdh> .
    • + +
+
+
+
+ + +

A. Embedding Turtle in HTML documents

This section is non-normative.

+

HTML [HTML5] script tags + + + + can be used to embed data blocks in documents. Turtle can be easily embedded in HTML this way.

+
Example 28
<script type="text/turtle">
+@prefix dc: <http://purl.org/dc/terms/> .
+@prefix frbr: <http://purl.org/vocab/frbr/core#> .
+
+<http://books.example.com/works/45U8QJGZSQKDH8N> a frbr:Work ;
+     dc:creator "Wil Wheaton"@en ;
+     dc:title "Just a Geek"@en ;
+     frbr:realization <http://books.example.com/products/9780596007683.BOOK>,
+         <http://books.example.com/products/9780596802189.EBOOK> .
+
+<http://books.example.com/products/9780596007683.BOOK> a frbr:Expression ;
+     dc:type <http://books.example.com/product-types/BOOK> .
+
+<http://books.example.com/products/9780596802189.EBOOK> a frbr:Expression ;
+     dc:type <http://books.example.com/product-types/EBOOK> .
+</script>
+

Turtle content should be placed in a script tag with the + type attribute set to text/turtle. < and > symbols + do not need to be escaped inside of script tags. The character encoding of the embedded Turtle + will match the HTML documents encoding.

+
+

A.1 XHTML

This section is non-normative.

+

+ Like JavaScript, Turtle authored for HTML (text/html) can break when used in XHTML + (application/xhtml+xml). The solution is the same one used for JavaScript. +

+
Example 29
<script type="text/turtle">
+# <![CDATA[
+@prefix frbr: <http://purl.org/vocab/frbr/core#> .
+
+<http://books.example.com/works/45U8QJGZSQKDH8N> a frbr:Work .
+# ]]>
+</script>
+

When embedded in XHTML Turtle data blocks must be enclosed in CDATA sections. Those CDATA markers must be in Turtle comments. If the character sequence "]]>" occurs in the document it must be escaped using strings escapes (\u005d\u0054\u003e). This will also make Turtle safe in polyglot documents served as both text/html + and application/xhtml+xml. Failing to use CDATA sections or escape "]]>" may result in a non well-formed XML document.

+
+
+

A.2 Parsing Turtle in HTML

This section is non-normative.

+

There are no syntactic or grammar differences between parsing Turtle that has been embedded + and normal Turtle documents. A Turtle document parsed from an HTML DOM will be a stream of character data rather than a stream of UTF-8 encoded bytes. No decoding is necessary if the HTML document has already been parsed into DOM. Each script data block is considered to be it's own Turtle document. @prefix and @base declarations in a Turtle data bloc are scoped to that data block and do not effect other data blocks. +The HTML lang attribute or XHTML xml:lang attribute have no effect on the parsing of the data blocks. +The base URI of the encapsulating HTML document provides a "Base URI Embedded in Content" per RFC3986 section 5.1.1. + + +

+
+
+ + +

B. Internet Media Type, File Extension and Macintosh File Type

+
+
Contact:
+
Eric Prud'hommeaux
+
See also:
+ +
How to Register a Media Type for a W3C Specification
+
Internet Media Type registration, consistency of use
TAG Finding 3 June 2002 (Revised 4 September 2002)
+
+

The Internet Media Type / MIME Type for Turtle is "text/turtle".

+

It is recommended that Turtle files have the extension ".ttl" (all lowercase) on all platforms.

+ +

It is recommended that Turtle files stored on Macintosh HFS file systems be given a file type of "TEXT".

+

This information that follows has been submitted to the IESG for review, approval, and registration with IANA.

+
+
Type name:
+
text
+ +
Subtype name:
+
turtle
+
Required parameters:
+
None
+
Optional parameters:
+
charset — this parameter is required when transferring non-ASCII data. If present, the value of charset is always UTF-8.
+ +
Encoding considerations:
+
The syntax of Turtle is expressed over code points in Unicode [UNICODE]. The encoding is always UTF-8 [UTF-8].
+
Unicode code points may also be expressed using an \uXXXX (U+0000 to U+FFFF) or \UXXXXXXXX syntax (for U+10000 onwards) where X is a hexadecimal digit [0-9A-Fa-f]
+
Security considerations:
+
Turtle is a general-purpose assertion language; applications may evaluate given data to infer more assertions or to dereference IRIs, invoking the security considerations of the scheme for that IRI. Note in particular, the privacy issues in [RFC3023] section 10 for HTTP IRIs. Data obtained from an inaccurate or malicious data source may lead to inaccurate or misleading conclusions, as well as the dereferencing of unintended IRIs. Care must be taken to align the trust in consulted resources with the sensitivity of the intended use of the data; inferences of potential medical treatments would likely require different trust than inferences for trip planning.
+ +
Turtle is used to express arbitrary application data; security considerations will vary by domain of use. Security tools and protocols applicable to text (e.g. PGP encryption, MD5 sum validation, password-protected compression) may also be used on Turtle documents. Security/privacy protocols must be imposed which reflect the sensitivity of the embedded information.
+
Turtle can express data which is presented to the user, for example, RDF Schema labels. Application rendering strings retrieved from untrusted Turtle documents must ensure that malignant strings may not be used to mislead the reader. The security considerations in the media type registration for XML ([RFC3023] section 10) provide additional guidance around the expression of arbitrary data and markup.
+
Turtle uses IRIs as term identifiers. Applications interpreting data expressed in Turtle should address the security issues of + Internationalized Resource Identifiers (IRIs) [RFC3987] Section 8, as well as + Uniform Resource Identifier (URI): Generic Syntax [RFC3986] Section 7.
+ +
Multiple IRIs may have the same appearance. Characters in different scripts may + look similar (a Cyrillic "о" may appear similar to a Latin "o"). A character followed + by combining characters may have the same visual representation as another character + (LATIN SMALL LETTER E followed by COMBINING ACUTE ACCENT has the same visual representation + as LATIN SMALL LETTER E WITH ACUTE). + + + + Any person or application that is writing or interpreting data in Turtle must take care to use the IRI that matches the intended semantics, and avoid IRIs that make look similar. + Further information about matching of similar characters can be found + in Unicode Security + Considerations [UNICODE-SECURITY] and + Internationalized Resource + Identifiers (IRIs) [RFC3987] Section 8. + + + +
+ +
Interoperability considerations:
+
There are no known interoperability issues.
+
Published specification:
+
This specification.
+
Applications which use this media type:
+ +
No widely deployed applications are known to use this media type. It may be used by some web services and clients consuming their data.
+
Additional information:
+
Magic number(s):
+
Turtle documents may have the strings '@prefix' or '@base' (case sensitive) or the strings 'PREFIX' or 'BASE' (case insensitive) near the beginning of the document.
+
File extension(s):
+
".ttl"
+ +
Base URI:
+
The Turtle '@base <IRIref>' or 'BASE <IRIref>' term can change the current base URI for relative IRIrefs in the query language that are used sequentially later in the document.
+
Macintosh file type code(s):
+
"TEXT"
+
Person & email address to contact for further information:
+ +
Eric Prud'hommeaux <eric@w3.org>
+
Intended usage:
+
COMMON
+
Restrictions on usage:
+
None
+
Author/Change controller:
+ +
The Turtle specification is the product of the RDF WG. The W3C reserves change control over this specifications.
+
+
+ + + +
+ + +

C. Acknowledgements

+ +

This work was described in the paper + New Syntaxes for RDF + which discusses other RDF syntaxes and the background + to the Turtle (Submitted to WWW2004, referred to as N-Triples + Plus there).

+ +

This work was started during the + Semantic Web Advanced Development Europe (SWAD-Europe) + project funded by the EU IST-7 programme IST-2001-34732 (2002-2004) + and further development supported by the + Institute for Learning and Research Technology at the University of Bristol, UK (2002-Sep 2005). +

+ +

Valuable contributions to this version were made by Gregg + Kellogg, Andy Seaborn, Sandro Hawke and the members of the RDF Working Group.

+

The document was improved through the review process by the wider community.

+ +
+
+ + +

D. Change Log

+ +
+

D.1 Changes since January + 2014 Proposed Recommendation

+
    +
  • Missing prefix added in example 11 in response to comment + from Lars Svensson.
    • +
  • Error + in grammar productions [21] and [23] fixed.
    • +
  • Error + in grammar productions [24] and [25] fixed.
    • +
+
+
+

D.2 Changes from February + 2013 Candidate Recommendation to January + 2014 Proposed Recommendation

+
    +
  • The addition of sparqlPrefix and sparqlBase which allow for using SPARQL style BASE and PREFIX directives in a Turtle document was marked "at risk" in the Candidate Recommendation publication. This feature is no longer at risk.
    • +
  • The title of this document was changed from + "Turtle" to "RDF 1.1 Turtle".
    • +
  • Removed the obsolete links to tests in Sec. 7.1.
    • +
+
+ +
+

D.3 Changes from August 2011 First Public Working Draft to Candidate Recommendation

+
    +
  • Renaming for STRING_* productions to STRING_LITERAL_QUOTE sytle names rather than numbers +
  • Local part of prefix names can now include ":" +
  • Turtle in HTML +
  • Renaming of grammar tokens and rules around IRIs +
  • Reserved character escape sequences +
  • String escape sequences limited to strings +
  • Numeric escape sequences limited to IRIs and Strings +
  • Support top-level blank-predicate-object lists +
  • Whitespace required between @prefix and prefix label +
+
+
+

D.4 Changes from January 2008 Team Submission to First Public Working Draft

+
    + +
  • Adopted three additional string syntaxes from SPARQL: STRING_LITERAL2, STRING_LITERAL_LONG1, STRING_LITERAL_LONG2
    • + +
  • Adopted SPARQL's syntax for prefixed names (see editor's draft): +
      +
    • '.'s in names in all positions of a local name apart from the first or last, e.g. ex:first.name.
      • + +
    • digits in the first character of the PN_LOCAL lexical token, e.g. ex:7tm.
      • +
    • +
  • adopted SPARQL's IRI resolution and prefix substitution text.
    • + +
  • explicitly allowed re-use of the same prefix.
    • +
  • Added parsing rules.
    • +
+ +

+ See also the pre-W3C Submission changelog. +

+ +
+ +
+ + + + + + + + +
+ +

E. References

E.1 Normative references

[BCP47]
A. Phillips; M. Davis. Tags for Identifying Languages. September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47 +
[EBNF-NOTATION]
Tim Bray; Jean Paoli; C. M. Sperberg-McQueen; Eve Maler; François Yergeau. EBNF Notation 26 November 2008. W3C Recommendation. URL: http://www.w3.org/TR/REC-xml/#sec-notation +
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-concepts/ +
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt +
[RFC3023]
M. Murata; S. St.Laurent; D. Kohn. XML Media Types (RFC 3023). January 2001. RFC. URL: http://www.ietf.org/rfc/rfc3023.txt +
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax (RFC 3986). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt +
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). January 2005. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt +
[UNICODE]
The Unicode Standard. URL: http://www.unicode.org/versions/latest/ +
[UTF-8]
F. Yergeau. UTF-8, a transformation format of ISO 10646. IETF RFC 3629. November 2003. URL: http://www.ietf.org/rfc/rfc3629.txt +

E.2 Informative references

[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. HTML5. 4 February 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/ +
[N-TRIPLES]
Gavin Carothers, Andy Seabourne. RDF 1.1 N-Triples. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-n-triples-20140225/. The latest edition is available at http://www.w3.org/TR/n-triples/ +
[RDF11-MT]
Patrick J. Hayes, Peter F. Patel-Schneider. RDF 1.1 Semantics. W3C Recommendation, 25 February 2014. URL: http://www.w3.org/TR/2014/REC-rdf11-mt-20140225/. The latest edition is available at http://www.w3.org/TR/rdf11-mt/ +
[SPARQL11-QUERY]
Steven Harris; Andy Seaborne. SPARQL 1.1 Query Language. 21 March 2013. W3C Recommendation. URL: http://www.w3.org/TR/sparql11-query/ +
[UNICODE-SECURITY]
Mark Davis; Michel Suignard. Unicode Security Considerations. URL: http://www.unicode.org/reports/tr36/ +
\ No newline at end of file diff --git a/docs/standards/references/w3c-document-license-2002.html b/docs/standards/references/w3c-document-license-2002.html new file mode 100644 index 0000000..78fff84 --- /dev/null +++ b/docs/standards/references/w3c-document-license-2002.html @@ -0,0 +1,389 @@ + + + + Document license - 2002 version | Copyright | W3C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + + + + +
+ + +
+ + + + + + + + +
+
+

Document license - 2002 version

+ + +
+

Status: This document license was applied to documents published by W3C before 31 January 2015. On 1 February 2015 W3C adopted a more permissive document license and applied the new license to all W3C documents that had previously been made available under this license.

License

By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

Disclaimers

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Versions

Changes since the previous document

This formulation of W3C's notice and license became active on December 31, 2002. This version removes the copyright ownership notice such that this license can be used with materials other than those owned by W3C, moves information on style sheets, DTDs, and schemas to the Copyright FAQ, reflects that ERCIM is now a host of W3C, includes references to this specific dated version of the license, and removes the ambiguous grant of "use".

Please see our Copyright FAQ for common questions about using materials from our site, such as the translating or annotating specifications.

+
+ + +
+
+ +
+ +
+
+
+ +
+ + + + + diff --git a/docs/standards/references/w3c-document-license.html b/docs/standards/references/w3c-document-license.html new file mode 100644 index 0000000..16f2c44 --- /dev/null +++ b/docs/standards/references/w3c-document-license.html @@ -0,0 +1,389 @@ + + + + Document license - 2023 version | Copyright | W3C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + + + + +
+ + +
+ + + + + + + + +
+
+

Document license - 2023 version

+ + +
+

Status: This document is in effect since 1 January 2023.

Public documents on the W3C site are provided by the copyright holders under the following license.

License

By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license, except as follows: To facilitate implementation of the technical specifications set forth in this document, anyone may prepare and distribute derivative works and portions of this document in software, in supporting materials accompanying software, and in documentation of software, PROVIDED that all such works include the notice below. HOWEVER, the publication of derivative works of this document for use as a technical specification is expressly prohibited.

In addition, "Code Components" —Web IDL in sections clearly marked as Web IDL; and W3C-defined markup (HTML, CSS, etc.) and computer programming language code clearly marked as code examples— are licensed under the W3C Software License.

The notice is:

"Copyright © 2023 W3C®. This software or document includes material copied from or derived from [title and URI of the W3C document]."

Disclaimers

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Versions

Changes since the previous document

  • The 2023 version updates the identification of the copyright holder.
+
+ + +
+
+ +
+ +
+
+
+ +
+ + + + + diff --git a/docs/standards/references/w3c-software-document-2015.html b/docs/standards/references/w3c-software-document-2015.html new file mode 100644 index 0000000..8fc9cd2 --- /dev/null +++ b/docs/standards/references/w3c-software-document-2015.html @@ -0,0 +1,389 @@ + + + + Software and Document license - 2015 version | Copyright | W3C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + + + + +
+ + +
+ + + + + + + + +
+
+

Software and Document license - 2015 version

+ + +
+

Status: This license was in effect between 13 May 2015 and 31 December 2022. It was replaced by this version.

This work is being provided by the copyright holders under the following license.

License

By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission to copy, modify, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:

  • The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  • Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C Software and Document Short Notice should be included.
  • Notice of any changes or modifications, through a copyright statement on the new code or document such as "This software or document includes material copied from or derived from [title and URI of the W3C document]. Copyright © [YEAR] W3C® (MIT, ERCIM, Keio, Beihang)."

Disclaimers

THIS WORK IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENT.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

Versions

Changes since the previous document

This version makes clear that the license is applicable to both software and text, by changing the name and substituting "work" for instances of "software and its documentation." It moves "notice of changes or modifications to the files" to the copyright notice, to make clear that the license is compatible with other liberal licenses.

+
+ + +
+
+ +
+ +
+
+
+ +
+ + + + + diff --git a/docs/standards/references/w3c-software-document-2023.html b/docs/standards/references/w3c-software-document-2023.html new file mode 100644 index 0000000..4c09eb1 --- /dev/null +++ b/docs/standards/references/w3c-software-document-2023.html @@ -0,0 +1,389 @@ + + + + Software and Document license - 2023 version | Copyright | W3C + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + + + + +
+ + +
+ + + + + + + + +
+
+

Software and Document license - 2023 version

+ + +
+

Status: This document is in effect since 1 January 2023.

This work is being provided by the copyright holders under the following license.

License

By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission to copy, modify, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:

  • The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  • Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C software and document short notice should be included.
  • Notice of any changes or modifications, through a copyright statement on the new code or document such as "This software or document includes material copied from or derived from [title and URI of the W3C document]. Copyright © [$year-of-document] World Wide Web Consortium. https://www.w3.org/copyright/software-license-2023/"

Disclaimers

THIS WORK IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENT.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

Versions

Changes since the previous document

  • The 2023 version updates identification of the copyright holder.
+
+ + +
+
+ +
+ +
+
+
+ +
+ + + + + diff --git a/docs/standards/references/xml-names.html b/docs/standards/references/xml-names.html new file mode 100644 index 0000000..095ae6a --- /dev/null +++ b/docs/standards/references/xml-names.html @@ -0,0 +1,925 @@ + + +Namespaces in XML 1.0 (Third Edition)

W3C

+

Namespaces in XML 1.0 (Third Edition)

+

W3C Recommendation 8 December 2009

This version:
+ + +http://www.w3.org/TR/2009/REC-xml-names-20091208/ +
Latest version:
+ + +http://www.w3.org/TR/xml-names/ +
Previous versions:
+ + +http://www.w3.org/TR/2006/REC-xml-names-20060816/ + http://www.w3.org/TR/2009/PER-xml-names-20090806/ +
Editors:
Tim Bray, Textuality <tbray@textuality.com>
Dave Hollander, Contivo, Inc. <dmh@contivo.com>
Andrew Layman, Microsoft <andrewl@microsoft.com>
Richard Tobin, University of Edinburgh and Markup Technology Ltd <richard@inf.ed.ac.uk>
Henry S. Thompson, University of Edinburgh and W3C <ht@w3.org> - Third Edition +

Please refer to the errata for this document, which may + include normative corrections.

See also translations.

This document is also available in these non-normative formats: XML and HTML highlighting +differences from the second edition.

Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

+

Status of this Document

+This section describes the status of this document at the time +of its publication. Other documents may supersede this document. +A list of current W3C publications and the latest revision of +this technical report can be found in the +W3C technical reports index +at http://www.w3.org/TR/. +

+This document is a product of the +XML Core Working Group +as part of the +W3C XML Activity. +The English version of this specification is the only normative version. +However, for translations of this document, see + +http://www.w3.org/2003/03/Translations/byTechnology?technology=xml-names +. +

+Known implementations are documented in the + +Namespaces 1.1 implementation report +(all known Namespaces 1.1 implementations also support Namespaces 1.0) +. +A test suite is also available via the +XML Test Suite +page. +

+This third edition incorporates all known errata as of the publication date. +It supersedes the previous + +edition of 16 August 2006.

This edition has been widely reviewed. Only minor editorial changes +have been made since the 6 August 2009 Proposed Edited Recommendation.

+Please report errors in this document to +xml-names-editor@w3.org; +public +archives +are available. The errata list for this document +is available at + +http://www.w3.org/XML/2009/xml-names-errata +. +

This document has been reviewed by W3C Members, by software +developers, and by other W3C groups and interested parties, and is +endorsed by the Director as a W3C Recommendation. It is a stable +document and may be used as reference material or cited from another +document. W3C's role in making the Recommendation is to draw attention +to the specification and to promote its widespread deployment. This +enhances the functionality and interoperability of the Web.

+W3C maintains a +public +list of any patent disclosures +made in connection with the deliverables of +the group; that page also includes instructions for disclosing a patent. +An individual who has actual knowledge of a patent which the individual +believes contains +Essential +Claim(s) +must disclose the information in accordance with +section +6 of the W3C Patent Policy. +

+

Table of Contents

1 Motivation and Summary
+    1.1 A Note on Notation and Usage
+2 XML Namespaces
+    2.1 Basic Concepts
+    2.2 Use of + +URIs +as Namespace Names
+    2.3 Comparing + +URI +References
+3 Declaring Namespaces
+4 Qualified Names
+5 Using Qualified Names
+6 Applying Namespaces to Elements and Attributes
+    6.1 Namespace Scoping
+    6.2 Namespace Defaulting
+    6.3 Uniqueness of Attributes
+7 Conformance of Documents
+8 Conformance of Processors
+

+

Appendices

A Normative References
+B Other references (Non-Normative)
+C The Internal Structure of XML Namespaces (Non-Normative)
+D Changes since version 1.0 (Non-Normative)
+E Acknowledgements (Non-Normative)
+F Orphaned Productions (Non-Normative)
+

+

1 Motivation and Summary

We envision applications of Extensible Markup Language (XML) where +a single XML document may +contain elements and attributes +(here referred to as a "markup vocabulary") +that are defined for and used by multiple software modules. +One motivation for this is modularity: if such a markup vocabulary exists +which is well-understood and for which there is useful software +available, it is better to re-use this markup rather than re-invent it. +

Such documents, containing multiple markup vocabularies, +pose problems of recognition and collision. Software modules need to +be able to recognize the elements and attributes which they are designed +to process, even in the face +of "collisions" occurring when markup intended for some other software +package uses the same element name +or attribute name. +

+These considerations require that document constructs +should have names constructed so as to avoid clashes +between names from different markup vocabularies. +This specification describes a mechanism, +XML namespaces, which accomplishes this +by assigning expanded names +to elements and attributes. +

+

1.1 A Note on Notation and Usage

+Where EMPHASIZED, the key words +MUST, +MUST NOT, +REQUIRED, +SHOULD, +SHOULD NOT, +MAY +in this document are to be interpreted as described in +[Keywords]. +

Note that many of the +nonterminals in the productions in +this specification are defined not here but in +the XML specification [XML]. +When nonterminals defined here have the same names as nonterminals +defined in the XML specification, the productions here +in all cases match a subset of the strings matched by the +corresponding ones there. +

In this document's productions, +the NSC is a "Namespace Constraint", +one of the rules that documents conforming to this specification +MUST +follow. +

+

2 XML Namespaces

+

2.1 Basic Concepts

+[Definition: +An XML namespace is identified by + + +a URI reference [RFC3986]; +element and attribute names +may be placed in an XML namespace using the mechanisms described +in this specification. +] +

+[Definition: +An expanded name +is a pair consisting of a +namespace name +and a +local name. +] + +[Definition: +For a name N in a namespace identified +by + +a URI +I, the +namespace name +is I. For a name N that is not in a namespace, the +namespace name +has no value. +] + +[Definition: +In either case the +local name +is N. +] + +It is this combination of the universally managed URI namespace +with the vocabulary's local names that is effective in avoiding +name clashes. +

+ +URI +references can contain characters not allowed in names, and are often +inconveniently long, so expanded names are not used directly to name +elements and attributes in XML documents. Instead +qualified names +are used. +[Definition: +A +qualified name +is a name subject to namespace interpretation. +] +In documents conforming to this specification, +element and attribute names appear as qualified names. +Syntactically, they are either +prefixed names or +unprefixed names. +An attribute-based declaration syntax is provided to bind prefixes to +namespace names and to bind a default namespace that applies to +unprefixed element names; +these declarations are scoped by the elements on which they appear so that +different bindings may apply in different parts of a document. +Processors conforming to this specification +MUST +recognize and act on these declarations and prefixes. +

+

2.2 Use of + +URIs +as Namespace Names

+The empty string, though it is a legal + +URI +reference, cannot be used as a namespace name. +

+The use of relative + +URI +references, +including same-document references, in namespace declarations is +deprecated. +

Note:

+This deprecation of relative URI references was decided on by a +W3C XML Plenary Ballot [Relative URI deprecation]. It also declares that +"later specifications such as DOM, XPath, etc. will define no +interpretation for them". +

+

2.3 Comparing + +URI +References

+ +URI +references identifying namespaces are compared when determining +whether a name belongs to a given namespace, and whether two names +belong to the same namespace. +[Definition: +The two + +URIs +are treated as strings, and they are +identical +if and only if the strings are identical, that is, if they +are the same sequence of characters. +] +The comparison is case-sensitive, and no %-escaping is done or undone. +

+A consequence of this is that + +URI +references which are not identical +in this sense may resolve to the same resource. Examples include + +URI +references which differ only in case or %-escaping, or which are +in external entities which have different base URIs (but note that +relative + +URIs +are deprecated as namespace names). +

+In a namespace declaration, the + +URI +reference is the +normalized value +of the attribute, so replacement of XML character and entity references +has already been done before any comparison. +

Examples:

+The + +URI +references below are all different for the purposes of identifying +namespaces, since they differ in case: +

  • +http://www.example.org/wine +

  • +http://www.Example.org/wine +

  • +http://www.example.org/Wine +

+The URI references below are also all different for the purposes of identifying +namespaces: +

  • +http://www.example.org/~wilbur +

  • +http://www.example.org/%7ewilbur +

  • +http://www.example.org/%7Ewilbur +

+Because of the risk of confusion between + +URIs +that would be equivalent +if dereferenced, the use of %-escaped characters in namespace names is +strongly discouraged. +

+

3 Declaring Namespaces

[Definition: A namespace +(or more precisely, a namespace binding) +is +declared using +a family of reserved attributes. +Such an attribute's name must either +be xmlns or begin xmlns:. +These attributes, like any other XML attributes, may be provided +directly or by default. +] +

+
Attribute Names for Namespace Declaration
[1]   NSAttName   ::=   PrefixedAttName
| DefaultAttName
[2]   PrefixedAttName   ::=   'xmlns:' NCName[NSC: Reserved Prefixes and Namespace Names]
[3]   DefaultAttName   ::=   'xmlns'
[4]   NCName   ::=   Name - (Char* ':' Char*)/* An XML +Name, minus the ":" */

+ +The attribute's +normalized value +MUST +be either + +a URI +reference — the +namespace name +identifying the namespace — +or an empty string. + +The namespace name, to serve its +intended purpose, +SHOULD +have the characteristics of uniqueness and +persistence. +It is not a goal that it be directly usable for retrieval of a schema (if +any exists). +Uniform Resource Names [RFC2141] is an example of a syntax that +is designed with these goals in mind. +However, it should be noted that ordinary URLs can be managed in such a way as +to achieve these same goals.

+[Definition: If the +attribute name matches PrefixedAttName, +then the +NCName gives the namespace prefix, +used to associate element and attribute names with the +namespace name in the attribute value +in the scope of the element to which the declaration +is attached. + +] +

[Definition: If the +attribute name matches DefaultAttName, +then the +namespace name in the +attribute value is +that of the default namespace +in the scope of the element to which the declaration +is attached.] +Default namespaces and overriding of declarations are discussed in +6 Applying Namespaces to Elements and Attributes. +

An example namespace declaration, which associates the +namespace prefix edi with the namespace name +http://ecommerce.example.org/schema: +

<x xmlns:edi='http://ecommerce.example.org/schema'>
+  <!-- the "edi" prefix is bound to http://ecommerce.example.org/schema
+       for the "x" element and contents -->
+</x>
+

Namespace constraint: Reserved Prefixes and Namespace Names

+ +

+The prefix xml is by definition bound to the namespace name +http://www.w3.org/XML/1998/namespace. It +MAY, +but need not, be +declared, and +MUST NOT +be + +bound to any other namespace name. Other prefixes +MUST NOT +be bound to this namespace +name, +and it +MUST NOT +be declared as the default namespace. +

+ +

+The prefix xmlns is used only to declare namespace bindings and is by +definition bound to the namespace name +http://www.w3.org/2000/xmlns/. It +MUST NOT +be declared +. +Other prefixes +MUST NOT +be bound to this namespace +name, +and it +MUST NOT +be declared as the default namespace. + +Element names +MUST NOT +have the prefix +xmlns. + +

+ +

+All other prefixes beginning with the three-letter sequence x, m, l, +in any case combination, are reserved. This means that: +

+ +

  • users +SHOULD NOT + use them except as defined by later specifications

  • processors +MUST NOT +treat them as fatal errors.

+ +

+Though they are not themselves reserved, it is inadvisable to use +prefixed names whose LocalPart begins with the letters x, m, l, in any +case combination, as +these names would be reserved if used without a prefix. +

+

4 Qualified Names

In XML +documents conforming to this specification, some +names (constructs corresponding to the nonterminal +Name) + +MUST +be given as +qualified names, +defined as follows: +

+
Qualified Name
[7]   QName   ::=   PrefixedName
| UnprefixedName
[8]   PrefixedName   ::=    +Prefix ':' LocalPart +
[9]   UnprefixedName   ::=    +LocalPart +
[10]   Prefix   ::=   NCName
[11]   LocalPart   ::=   NCName

+The +Prefix provides the +namespace prefix +part of the qualified name, and +MUST +be associated with a namespace + +URI +reference in a +namespace declaration. +[Definition: +The LocalPart provides the +local part of the qualified name.] +

Note that the prefix functions only as a placeholder for a +namespace name. +Applications +SHOULD +use the namespace name, not the prefix, in constructing +names whose scope extends beyond the +containing document.

+

5 Using Qualified Names

In XML documents conforming to this specification, +element names are given as +qualified names, as +follows: +

+
Element Names
[12]   STag   ::=   '<' QName +(S +Attribute)* +S? '>' +[NSC: Prefix Declared]
[13]   ETag   ::=   '</' QName +S? '>'[NSC: Prefix Declared]
[14]   EmptyElemTag   ::=   '<' QName +(S +Attribute)* +S? '/>'[NSC: Prefix Declared]

An example of a qualified name serving as an element name: +

+  <!-- the 'price' element's namespace is http://ecommerce.example.org/schema -->
+  <edi:price xmlns:edi='http://ecommerce.example.org/schema' units='Euro'>32.18</edi:price>
+

+Attributes are either namespace +declarations +or their names are given as +qualified names: +

+
Attribute
[15]   Attribute   ::=   NSAttName +Eq +AttValue
| QName Eq +AttValue[NSC: Prefix Declared]
[NSC: No Prefix Undeclaring]
[NSC: Attributes Unique]

An example of a qualified name serving as an attribute name: +

<x xmlns:edi='http://ecommerce.example.org/schema'>
+  <!-- the 'taxClass' attribute's namespace is http://ecommerce.example.org/schema -->
+  <lineItem edi:taxClass="exempt">Baby food</lineItem>
+</x>
+

Namespace constraint: Prefix Declared

+

The namespace prefix, unless it is xml +or xmlns, +MUST +have been +declared in a namespace declaration +attribute in either the start-tag of the element where the prefix +is used or in an ancestor element (i.e., an element in whose +content the +prefixed markup occurs). + +

+

Namespace constraint: No Prefix Undeclaring

+

In a namespace declaration for a prefix (i.e., + where the NSAttName is a PrefixedAttName), the attribute value MUST NOT be empty.

+

This constraint may lead to operational difficulties in the case where +the namespace declaration attribute is provided, not directly in the XML +document entity, but +via a default attribute declared in an external entity. +Such declarations may not be read by software which is based on a +non-validating XML processor. +Many XML applications, presumably including namespace-sensitive ones, fail to +require validating processors. +If correct operation with such applications is required, +namespace declarations +MUST +be +provided either directly or via default attributes declared in the +internal subset of the DTD. +

Element names and attribute names are also given as qualified names when +they appear in declarations in the +DTD: +

+
Qualified Names in Declarations
[16]   doctypedecl   ::=   '<!DOCTYPE' S +QName (S +ExternalID)? +S? ('[' +(markupdecl +| PEReference +| S)* +']' +S?)? '>'
[17]   elementdecl   ::=   '<!ELEMENT' S +QName +S +contentspec +S? '>'
[18]   cp   ::=   (QName +| choice +| seq) +('?' | '*' | '+')?
[19]   Mixed   ::=   '(' S? +'#PCDATA' +(S? +'|' +S? +QName)* +S? +')*'
| '(' S? '#PCDATA' S? ')' +
[20]   AttlistDecl   ::=   '<!ATTLIST' S +QName +AttDef* +S? '>'
[21]   AttDef   ::=   S +(QName | NSAttName) +S AttType +S DefaultDecl

+Note that DTD-based validation is not namespace-aware in the following +sense: a DTD constrains the elements and attributes that may appear in +a document by their uninterpreted names, not by (namespace name, local +name) pairs. To validate a document that uses namespaces against a +DTD, the same prefixes must be used in the DTD as in the instance. +A DTD may however indirectly constrain the namespaces used in a valid +document by providing #FIXED values for attributes that +declare namespaces. +

+

6 Applying Namespaces to Elements and Attributes

+

6.1 Namespace Scoping

+The scope of a namespace declaration declaring a prefix extends from +the beginning of the start-tag in which it appears to the end of the +corresponding end-tag, excluding the scope of any inner declarations +with the same NSAttName part. +In the case of an empty tag, the scope is the tag itself. +

+Such a namespace declaration applies to all element and attribute +names within its scope whose prefix matches that specified in the +declaration. +

+The +expanded name +corresponding to a prefixed element or attribute name has the + +URI +to which the +prefix +is bound as its +namespace name, +and the +local part +as its +local name. +

<?xml version="1.0"?>
+
+<html:html xmlns:html='http://www.w3.org/1999/xhtml'>
+
+  <html:head><html:title>Frobnostication</html:title></html:head>
+  <html:body><html:p>Moved to 
+    <html:a href='http://frob.example.com'>here.</html:a></html:p></html:body>
+</html:html>

Multiple namespace prefixes can be declared as attributes of a single element, +as shown in this example: +

<?xml version="1.0"?>
+<!-- both namespace prefixes are available throughout -->
+<bk:book xmlns:bk='urn:loc.gov:books'
+         xmlns:isbn='urn:ISBN:0-395-36341-6'>
+    <bk:title>Cheaper by the Dozen</bk:title>
+    <isbn:number>1568491379</isbn:number>
+</bk:book>
+

6.2 Namespace Defaulting

+The scope of a +default namespace declaration +extends from the beginning of the +start-tag in which it appears to the end of the corresponding end-tag, +excluding the scope of any inner default namespace declarations. +In the case of an empty tag, the scope is the tag itself. +

+A default namespace declaration applies to all unprefixed element names +within its scope. +Default namespace declarations do not apply directly to attribute names; +the interpretation of unprefixed attributes is +determined by the element on which they appear. +

+If there is a default namespace declaration in scope, the +expanded name +corresponding to an unprefixed element name has the + +URI +of the +default namespace +as its +namespace name. +If there is no default namespace declaration in scope, the +namespace name has no value. +The namespace name for an unprefixed attribute name always has no value. +In all cases, the +local name is +local part +(which is of course the same as the unprefixed name itself). +

<?xml version="1.0"?>
+<!-- elements are in the HTML namespace, in this case by default -->
+<html xmlns='http://www.w3.org/1999/xhtml'>
+  <head><title>Frobnostication</title></head>
+  <body><p>Moved to 
+    <a href='http://frob.example.com'>here</a>.</p></body>
+</html>
<?xml version="1.0"?>
+<!-- unprefixed element types are from "books" -->
+<book xmlns='urn:loc.gov:books'
+      xmlns:isbn='urn:ISBN:0-395-36341-6'>
+    <title>Cheaper by the Dozen</title>
+    <isbn:number>1568491379</isbn:number>
+</book>

A larger example of namespace scoping: +

<?xml version="1.0"?>
+<!-- initially, the default namespace is "books" -->
+<book xmlns='urn:loc.gov:books'
+      xmlns:isbn='urn:ISBN:0-395-36341-6'>
+    <title>Cheaper by the Dozen</title>
+    <isbn:number>1568491379</isbn:number>
+    <notes>
+      <!-- make HTML the default namespace for some commentary -->
+      <p xmlns='http://www.w3.org/1999/xhtml'>
+          This is a <i>funny</i> book!
+      </p>
+    </notes>
+</book>

The attribute value in a default namespace declaration +MAY +be empty. +This has the same +effect, within the scope of the declaration, of there being no default +namespace. +

<?xml version='1.0'?>
+<Beers>
+  <!-- the default namespace inside tables is that of HTML -->
+  <table xmlns='http://www.w3.org/1999/xhtml'>
+   <th><td>Name</td><td>Origin</td><td>Description</td></th>
+   <tr> 
+     <!-- no default namespace inside table cells -->
+     <td><brandName xmlns="">Huntsman</brandName></td>
+     <td><origin xmlns="">Bath, UK</origin></td>
+     <td>
+       <details xmlns=""><class>Bitter</class><hop>Fuggles</hop>
+         <pro>Wonderful hop, light alcohol, good summer beer</pro>
+         <con>Fragile; excessive variance pub to pub</con>
+         </details>
+        </td>
+      </tr>
+    </table>
+  </Beers>
+

6.3 Uniqueness of Attributes

+

Namespace constraint: Attributes Unique

+

In XML documents conforming +to this specification, no tag +may contain two attributes which: +

+

  1. have identical names, or

  2. have qualified names with the same +local part and with +prefixes which have been bound +to namespace names that +are identical. +

+

+This constraint is equivalent to requiring that no element have two +attributes with the same +expanded name. +

For example, each of the bad empty-element tags is illegal in the +following: +

<!-- http://www.w3.org is bound to n1 and n2 -->
+<x xmlns:n1="http://www.w3.org" 
+   xmlns:n2="http://www.w3.org" >
+  <bad a="1"     a="2" />
+  <bad n1:a="1"  n2:a="2" />
+</x>

+However, each of the following is legal, the second because the default +namespace does not apply to attribute names: +

<!-- http://www.w3.org is bound to n1 and is the default -->
+<x xmlns:n1="http://www.w3.org" 
+   xmlns="http://www.w3.org" >
+  <good a="1"     b="2" />
+  <good a="1"     n1:a="2" />
+</x>
+

7 Conformance of Documents

+This specification applies to XML 1.0 +documents. To conform to this +specification, a document +MUST +be well-formed according to the +XML 1.0 specification [XML]. +

+In XML documents which conform to this specification, element +and attribute names +MUST +match the production for +QName +and +MUST +satisfy the "Namespace Constraints". All other tokens in the +document which are +REQUIRED, + + +for XML 1.0 well-formedness, to match the +XML production for +Name + +MUST +match this specification's production for +NCName. +

+[Definition: +A document is namespace-well-formed +if it conforms to this specification. +] +

+It follows that in a namespace-well-formed document: +

  • All element and attribute names contain either zero or one + colon;

  • No entity names, processing instruction targets, or notation names contain any colons.

+In addition, a namespace-well-formed document may also be namespace-valid. +

+[Definition: +A namespace-well-formed document is namespace-valid +if it is valid according to the XML 1.0 specification, and all tokens +other than element and attribute names which are +REQUIRED, +for XML 1.0 validity, to match the XML production for +Name +match this specification's production for +NCName. +] +

+It follows that in a namespace-valid document: +

  • + No attributes with a declared type of + ID, IDREF(S), ENTITY(IES), or NOTATION + contain any colons. +

+

8 Conformance of Processors

+To conform to this specification, a processor +MUST +report +violations of namespace well-formedness, with the exception that it +is not +REQUIRED +to check that namespace names are +URI references [RFC3986]. +

+[Definition: +A validating XML processor that conforms to this specification +is namespace-validating if in addition +it reports violations of namespace validity. +] +

+

A Normative References

Keywords
+RFC 2119: Key words for use in RFCs to Indicate Requirement Levels, +S. Bradner, ed. +IETF (Internet Engineering Task Force), +March 1997. +Available at +http://www.rfc-editor.org/rfc/rfc2119.txt +
RFC2141
+RFC 2141: URN Syntax, +R. Moats, ed. +IETF (Internet Engineering Task Force), +May 1997. + +Available at +http://www.rfc-editor.org/rfc/rfc2141.txt. + +
RFC3986
+RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, +T. Berners-Lee, R. Fielding, and L. Masinter, eds. +IETF (Internet Engineering Task Force), +January 2005. +Available at +http://www.rfc-editor.org/rfc/rfc3986.txt +
RFC3629
+RFC 3629: UTF-8, a transformation format of ISO 10646, +F. Yergeau, ed. +IETF (Internet Engineering Task Force), +November 2003. +Available at http://www.rfc-editor.org/rfc/rfc3629.txt +
XML
+Extensible Markup Language +(XML) 1.0, Tim Bray, Jean +Paoli, C. M. Sperberg-McQueen, Eve Maler, and François Yergeau eds. +W3C (World Wide Web Consortium). +Available at +http://www.w3.org/TR/REC-xml/. +
+

B Other references (Non-Normative)

1.0 Errata
+Namespaces in XML Errata. +W3C (World Wide Web Consortium). +Available at +http://www.w3.org/XML/xml-names-19990114-errata. +
1.0 2e Errata
+Namespaces in XML +(Second Edition) Errata. +W3C (World Wide Web Consortium). +Available at +http://www.w3.org/XML/2006/xml-names-errata. +
Relative URI deprecation
+ +Results of W3C XML Plenary +Ballot on relative URI References +In namespace declarations +3-17 July 2000, +Dave Hollander and +C. M. Sperberg-McQueen, +6 September 2000. +Available at +http://www.w3.org/2000/09/xppa. +
+

C The Internal Structure of XML Namespaces (Non-Normative)

+This appendix has been deleted. +

+

D Changes since version 1.0 (Non-Normative)

+This version incorporates the errata as of 20 July 2009 +[1.0 Errata] [1.0 2e Errata]. +

+There are several editorial changes, including a number +of terminology changes and additions intended to produce greater +consistency. The non-normative appendix "The Internal Structure +of XML Namespaces" has been removed. The BNF +has been adjusted to interconnect properly with all editions of XML 1.0, +including the fifth edition. +

+

E Acknowledgements (Non-Normative)

This work reflects input from a very large number of people, +including especially the participants in the World Wide +Web Consortium XML Working Group and Special Interest Group +and the participants in the W3C Metadata Activity. +The contributions of Charles Frankston of Microsoft +were particularly valuable.

+

F Orphaned Productions (Non-Normative)

The following two productions are modified versions of ones which were present in the first two editions of this specification. They are no longer used, but are retained here to satisfy cross-references to undated versions of this specification.

Because the Letter production of XML 1.0, originally used in the definition of NCNameStartChar, is no longer the correct basis for defining names since XML 1.0 Fifth Edition, the NCNameStartChar production has been modified to give the correct results against any edition of XML, by defining NCNameStartChar in terms of NCName.

[5]   NCNameChar   ::=   NameChar +- ':' /* An XML NameChar, minus the ":" */
[6]   NCNameStartChar   ::=    + NCName - ( Char Char Char* ) /* The first letter of an NCName */ +

Note:

Production + NC-NCNameStartChar + takes advantage of the fact that a + single-character NCName is necessarily an NCNameStartChar, and + works by subtracting from the set of NCNames of all lengths the + set of all strings of two or more characters, leaving only the + NCNames which are one character long.

diff --git a/docs/standards/references/xml.html b/docs/standards/references/xml.html new file mode 100644 index 0000000..a9e5a60 --- /dev/null +++ b/docs/standards/references/xml.html @@ -0,0 +1,2215 @@ + + +Extensible Markup Language (XML) 1.0 (Fifth Edition)

W3C

+

Extensible Markup Language (XML) 1.0 (Fifth Edition)

+

W3C Recommendation 26 November 2008

+
+

Note: On 7 February 2013, this specification was modified in place to replace broken links to RFC4646 and RFC4647.

+
+
This version:
+ http://www.w3.org/TR/2008/REC-xml-20081126/ +
Latest version:
+ http://www.w3.org/TR/xml/ +
Previous versions:
+ http://www.w3.org/TR/2008/PER-xml-20080205/ +
+ http://www.w3.org/TR/2006/REC-xml-20060816/ +
Editors:
Tim Bray, Textuality and Netscape <tbray@textuality.com>
Jean Paoli, Microsoft <jeanpa@microsoft.com>
C. M. Sperberg-McQueen, W3C <cmsmcq@w3.org>
Eve Maler, Sun Microsystems, Inc. <eve.maler@east.sun.com>
François Yergeau

Please refer to the errata for this document, which may + include some normative corrections.

The previous errata for this document, are also available.

See also translations.

This document is also available in these non-normative formats: XML and XHTML with color-coded revision indicators.

Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

+

Status of this Document

This section describes the status of this document at the time of its publication. + Other documents may supersede this document. A list of current W3C publications and the + latest revision of this technical report can be found in the W3C technical reports index at + http://www.w3.org/TR/.

This document specifies a syntax created by subsetting an existing, widely + used international text processing standard (Standard Generalized Markup Language, + ISO 8879:1986(E) as amended and corrected) for use on the World Wide Web. + It is a product of the XML Core Working Group + as part of the XML Activity. + The English version of this specification is the only normative version. However, + for translations of this document, see http://www.w3.org/2003/03/Translations/byTechnology?technology=xml.

This document is a W3C Recommendation. This fifth edition is not a new version of XML. As a convenience to readers, + it incorporates the changes dictated by the accumulated errata (available at + http://www.w3.org/XML/xml-V10-4e-errata) to the Fourth + Edition of XML 1.0, dated 16 August 2006. In particular, erratum [E09] + relaxes the restrictions on element and attribute names, thereby providing in XML 1.0 the major end user benefit + currently achievable only by using XML +1.1. As a consequence, many possible + documents which were not well-formed according to previous editions of this + specification are now well-formed, and previously invalid documents +using the newly-allowed name characters in, for example, ID +attributes, are now valid.

This edition supersedes the previous W3C Recommendation + of 16 August 2006.

Please report errors in this document to +the public xml-editor@w3.org mail list; public + archives are available. For the convenience of readers, + an XHTML version with color-coded revision indicators is + also provided; this version highlights each change due to an erratum published in the + errata +list for the previous edition, together with a link to the particular + erratum in that list. Most of the +errata in the list provide a rationale for the change. The errata +list for this fifth edition is available at http://www.w3.org/XML/xml-V10-5e-errata.

An implementation report is available at http://www.w3.org/XML/2008/01/xml10-5e-implementation.html. + A Test Suite is maintained to help assessing conformance to this specification.

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

W3C maintains a public list of + any patent disclosures made in connection with the deliverables of + the group; that page also includes instructions for disclosing a patent. + An individual who has actual knowledge of a patent which the individual + believes contains Essential + Claim(s) must disclose the information in accordance with + section 6 of the W3C Patent Policy.

+

Table of Contents

1 Introduction
+    1.1 Origin and Goals
+    1.2 Terminology
+2 Documents
+    2.1 Well-Formed XML Documents
+    2.2 Characters
+    2.3 Common Syntactic Constructs
+    2.4 Character Data and Markup
+    2.5 Comments
+    2.6 Processing Instructions
+    2.7 CDATA Sections
+    2.8 Prolog and Document Type Declaration
+    2.9 Standalone Document Declaration
+    2.10 White Space Handling
+    2.11 End-of-Line Handling
+    2.12 Language Identification
+3 Logical Structures
+    3.1 Start-Tags, End-Tags, and Empty-Element Tags
+    3.2 Element Type Declarations
+        3.2.1 Element Content
+        3.2.2 Mixed Content
+    3.3 Attribute-List Declarations
+        3.3.1 Attribute Types
+        3.3.2 Attribute Defaults
+        3.3.3 Attribute-Value Normalization
+    3.4 Conditional Sections
+4 Physical Structures
+    4.1 Character and Entity References
+    4.2 Entity Declarations
+        4.2.1 Internal Entities
+        4.2.2 External Entities
+    4.3 Parsed Entities
+        4.3.1 The Text Declaration
+        4.3.2 Well-Formed Parsed Entities
+        4.3.3 Character Encoding in Entities
+    4.4 XML Processor Treatment of Entities and References
+        4.4.1 Not Recognized
+        4.4.2 Included
+        4.4.3 Included If Validating
+        4.4.4 Forbidden
+        4.4.5 Included in Literal
+        4.4.6 Notify
+        4.4.7 Bypassed
+        4.4.8 Included as PE
+        4.4.9 Error
+    4.5 Construction of Entity Replacement Text
+    4.6 Predefined Entities
+    4.7 Notation Declarations
+    4.8 Document Entity
+5 Conformance
+    5.1 Validating and Non-Validating Processors
+    5.2 Using XML Processors
+6 Notation
+

+

Appendices

A References
+    A.1 Normative References
+    A.2 Other References
+B Character Classes
+C XML and SGML (Non-Normative)
+D Expansion of Entity and Character References (Non-Normative)
+E Deterministic Content Models (Non-Normative)
+F Autodetection of Character Encodings (Non-Normative)
+    F.1 Detection Without External Encoding Information
+    F.2 Priorities in the Presence of External Encoding Information
+G W3C XML Working Group (Non-Normative)
+H W3C XML Core Working Group (Non-Normative)
+I Production Notes (Non-Normative)
+J Suggestions for XML Names (Non-Normative)
+

+

1 Introduction

Extensible Markup Language, abbreviated XML, describes a class of data +objects called XML documents and partially +describes the behavior of computer programs which process them. XML is an +application profile or restricted form of SGML, the Standard Generalized Markup +Language [ISO 8879]. By construction, XML documents are conforming +SGML documents.

XML documents are made up of storage units called entities, +which contain either parsed or unparsed data. Parsed data is made up of characters, some of which form character +data, and some of which form markup. +Markup encodes a description of the document's storage layout and logical +structure. XML provides a mechanism to impose constraints on the storage layout +and logical structure.

+ [Definition: A software module called +an XML processor is used to read XML documents and provide access +to their content and structure.] + [Definition: It +is assumed that an XML processor is doing its work on behalf of another module, +called the application.] This specification describes +the required behavior of an XML processor in terms of how it must read XML +data and the information it must provide to the application.

+

1.1 Origin and Goals

XML was developed by an XML Working Group (originally known as the SGML +Editorial Review Board) formed under the auspices of the World Wide Web Consortium +(W3C) in 1996. It was chaired by Jon Bosak of Sun Microsystems with the active +participation of an XML Special Interest Group (previously known as the SGML +Working Group) also organized by the W3C. The membership of the XML Working +Group is given in an appendix. Dan Connolly served as the Working Group's contact with +the W3C.

The design goals for XML are:

  1. XML shall be straightforwardly usable over the Internet.

  2. XML shall support a wide variety of applications.

  3. XML shall be compatible with SGML.

  4. It shall be easy to write programs which process XML documents.

  5. The number of optional features in XML is to be kept to the absolute +minimum, ideally zero.

  6. XML documents should be human-legible and reasonably clear.

  7. The XML design should be prepared quickly.

  8. The design of XML shall be formal and concise.

  9. XML documents shall be easy to create.

  10. Terseness in XML markup is of minimal importance.

This specification, together with associated standards (Unicode [Unicode] + and ISO/IEC 10646 [ISO/IEC 10646] for characters, Internet BCP 47 + [IETF BCP 47] and the Language Subtag Registry [IANA-LANGCODES] for language + identification tags), provides +all the information necessary to understand XML Version 1.0 and +construct computer programs to process it.

This version of the XML specification may be distributed freely, as long as +all text and legal notices remain intact.

+

1.2 Terminology

The terminology used to describe XML documents is defined in the body of +this specification. The key words MUST, MUST NOT, +REQUIRED, SHALL, SHALL NOT, +SHOULD, SHOULD NOT, RECOMMENDED, +MAY, and OPTIONAL, when EMPHASIZED, +are to be interpreted as described in [IETF RFC 2119]. In addition, the terms defined +in the following list are used in building +those definitions and in describing the actions of an XML processor:

error

+ [Definition: A violation of the rules of this specification; +results are undefined. Unless otherwise specified, failure to observe a prescription of this specification indicated by one of the keywords MUST, REQUIRED, MUST NOT, SHALL and SHALL NOT is an error. Conforming software MAY detect and report an error +and MAY recover from it.] +

fatal error

+ [Definition: An error which a conforming XML processor + MUST detect and report to the application. +After encountering a fatal error, the processor MAY continue processing the +data to search for further errors and MAY report such errors to the application. +In order to support correction of errors, the processor MAY make unprocessed +data from the document (with intermingled character data and markup) available +to the application. Once a fatal error is detected, however, the processor +MUST NOT continue normal processing (i.e., it MUST NOT continue to pass character +data and information about the document's logical structure to the application +in the normal way).] +

at user option

+ [Definition: Conforming software +MAY or MUST (depending on the modal verb in the sentence) behave as described; +if it does, it MUST provide users a means to enable or disable the behavior +described.] +

validity constraint

+ [Definition: A rule which applies to +all valid XML documents. Violations of validity +constraints are errors; they MUST, at user option, be reported by validating XML processors.] +

well-formedness constraint

+ [Definition: A rule which applies +to all well-formed XML documents. Violations +of well-formedness constraints are fatal errors.] +

match

+ [Definition: (Of strings or names:) Two strings +or names being compared are identical. Characters with multiple possible +representations in ISO/IEC 10646 (e.g. characters with both precomposed and +base+diacritic forms) match only if they have the same representation in both +strings. No +case folding is performed. (Of strings and rules in the grammar:) A string +matches a grammatical production if it belongs to the language generated by +that production. (Of content and content models:) An element matches its declaration +when it conforms in the fashion described in the constraint [VC: Element Valid].] +

for compatibility

+ [Definition: Marks +a sentence describing a feature of XML included solely to ensure +that XML remains compatible with SGML.] +

for interoperability

+ [Definition: Marks +a sentence describing a non-binding recommendation included to increase +the chances that XML documents can be processed by the existing installed +base of SGML processors which predate the WebSGML Adaptations Annex to ISO 8879.] +

+

+

2 Documents

+ [Definition: A data object is an XML +document if it is well-formed, +as defined in this specification. In addition, the XML document is +valid if it meets certain further constraints.] +

Each XML document has both a logical and a physical structure. Physically, +the document is composed of units called entities. +An entity may + refer to other entities to +cause their inclusion in the document. A document begins in a "root" +or document entity. Logically, the document +is composed of declarations, elements, comments, character references, and +processing instructions, all of which are indicated in the document by explicit +markup. The logical and physical structures MUST nest properly, as described +in 4.3.2 Well-Formed Parsed Entities.

+

2.1 Well-Formed XML Documents

+ [Definition: A textual object is a well-formed +XML document if:] +

  1. Taken as a whole, it matches the production labeled document.

  2. It meets all the well-formedness constraints given in this specification.

  3. Each of the parsed entities +which is referenced directly or indirectly within the document is well-formed.

+
Document
[1]   document   ::=    + prolog + element + Misc*

Matching the document production implies that:

  1. It contains one or more elements.

  2. + [Definition: There is exactly one element, +called the root, or document element, no part of which appears +in the content of any other element.] For +all other elements, if the start-tag is in +the content of another element, the end-tag +is in the content of the same element. More simply stated, the elements, +delimited by start- and end-tags, nest properly within each other.

+ [Definition: As a consequence of this, +for each non-root element C in the document, there is one other element P +in the document such that C is in the content of P, but +is not in the content of any other element that is in the content of P. P +is referred to as the parent of C, and C as +a child of P.] +

+

2.2 Characters

+ [Definition: A parsed entity contains text, +a sequence of characters, which may +represent markup or character data.] + [Definition: A character +is an atomic unit of text as specified by ISO/IEC 10646:2000 [ISO/IEC 10646]. Legal characters are tab, carriage +return, line feed, and the legal characters +of Unicode and ISO/IEC 10646. The +versions of these standards cited in A.1 Normative References were +current at the time this document was prepared. New characters may be added +to these standards by amendments or new editions. Consequently, XML processors +MUST accept any character in the range specified for Char. +] +

+
Character Range
[2]   Char   ::=   #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]/* any Unicode character, excluding the surrogate blocks, FFFE, and FFFF. */

The mechanism for encoding character code points into bit patterns may +vary from entity to entity. All XML processors MUST accept the UTF-8 and UTF-16 +encodings of Unicode [Unicode]; +the mechanisms for signaling which of the two is in use, +or for bringing other encodings into play, are discussed later, in 4.3.3 Character Encoding in Entities.

Note:

Document authors are encouraged to avoid +"compatibility characters", as defined +in section 2.3 of [Unicode]. The characters defined in the following ranges are also +discouraged. They are either control characters or permanently undefined Unicode +characters:

[#x7F-#x84], [#x86-#x9F], [#xFDD0-#xFDEF],
+[#x1FFFE-#x1FFFF], [#x2FFFE-#x2FFFF], [#x3FFFE-#x3FFFF],
+[#x4FFFE-#x4FFFF], [#x5FFFE-#x5FFFF], [#x6FFFE-#x6FFFF],
+[#x7FFFE-#x7FFFF], [#x8FFFE-#x8FFFF], [#x9FFFE-#x9FFFF],
+[#xAFFFE-#xAFFFF], [#xBFFFE-#xBFFFF], [#xCFFFE-#xCFFFF],
+[#xDFFFE-#xDFFFF], [#xEFFFE-#xEFFFF], [#xFFFFE-#xFFFFF],
+[#x10FFFE-#x10FFFF].
+

2.3 Common Syntactic Constructs

This section defines some symbols used widely in the grammar.

+ S (white space) consists of one or more space (#x20) +characters, carriage returns, line feeds, or tabs.

+
White Space
[3]   S   ::=   (#x20 | #x9 | #xD | #xA)+

Note:

The presence of #xD in the above production is + maintained purely for backward compatibility with the + First Edition. + As explained in 2.11 End-of-Line Handling, + all #xD characters literally present in an XML document + are either removed or replaced by #xA characters before + any other processing is done. The only way to get a #xD character to match this production is to + use a character reference in an entity value literal.

An Nmtoken (name token) is any mixture of name +characters.

[Definition: A Name is an Nmtoken with a restricted set of initial characters.] Disallowed initial characters for Names include digits, diacritics, the full stop and the hyphen.

Names beginning with the string "xml", +or with any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), +are reserved for standardization in this or future versions of this specification.

Note:

The +Namespaces in XML Recommendation [XML Names] assigns a meaning +to names containing colon characters. Therefore, authors should not use the +colon in XML names except for namespace purposes, but XML processors must +accept the colon as a name character.

The first character of a Name MUST be a NameStartChar, and any + other characters MUST be NameChars; this mechanism is used to + prevent names from beginning with European (ASCII) digits or with + basic combining characters. Almost all characters are permitted in + names, except those which either are or reasonably could be used as + delimiters. The intention is to be inclusive rather than exclusive, + so that writing systems not yet encoded in Unicode can be used in + XML names. See J Suggestions for XML Names for suggestions on the creation of + names.

Document authors are encouraged to use names which are + meaningful words or combinations of words in natural languages, and + to avoid symbolic or white space characters in names. Note that + COLON, HYPHEN-MINUS, FULL STOP (period), LOW LINE (underscore), and + MIDDLE DOT are explicitly permitted.

The ASCII symbols and punctuation marks, along with a fairly + large group of Unicode symbol characters, are excluded from names + because they are more useful as delimiters in contexts where XML + names are used outside XML documents; providing this group gives + those contexts hard guarantees about what cannot be part of + an XML name. The character #x037E, GREEK QUESTION MARK, is excluded + because when normalized it becomes a semicolon, which could change + the meaning of entity references.

+
Names and Tokens
[4]   NameStartChar   ::=   ":" | [A-Z] | "_" | [a-z] | [#xC0-#xD6] | [#xD8-#xF6] | [#xF8-#x2FF] | [#x370-#x37D] | [#x37F-#x1FFF] | [#x200C-#x200D] | [#x2070-#x218F] | [#x2C00-#x2FEF] | [#x3001-#xD7FF] | [#xF900-#xFDCF] | [#xFDF0-#xFFFD] | [#x10000-#xEFFFF]
[4a]   NameChar   ::=   NameStartChar | "-" | "." | [0-9] | #xB7 | [#x0300-#x036F] | [#x203F-#x2040]
[5]   Name   ::=   NameStartChar (NameChar)*
[6]   Names   ::=   Name (#x20 Name)*
[7]   Nmtoken   ::=   (NameChar)+
[8]   Nmtokens   ::=   Nmtoken (#x20 Nmtoken)*

Note:

The Names +and Nmtokens productions are used to define the validity +of tokenized attribute values after normalization (see 3.3.1 Attribute Types).

Literal data is any quoted string not containing the quotation mark used +as a delimiter for that string. Literals are used for specifying the content +of internal entities (EntityValue), the values +of attributes (AttValue), and external identifiers +(SystemLiteral). Note that a SystemLiteral +can be parsed without scanning for markup.

+
Literals
[9]   EntityValue   ::=   '"' ([^%&"] | PEReference +| Reference)* '"'
|  "'" ([^%&'] | PEReference | Reference)* "'"
[10]   AttValue   ::=   '"' ([^<&"] | Reference)* +'"'
|  "'" ([^<&'] | Reference)* +"'"
[11]   SystemLiteral   ::=   ('"' [^"]* '"') | ("'" [^']* "'")
[12]   PubidLiteral   ::=   '"' PubidChar* '"' +| "'" (PubidChar - "'")* "'"
[13]   PubidChar   ::=   #x20 | #xD | #xA | [a-zA-Z0-9] | [-'()+,./:=?;!*#@$_%]

Note:

Although +the EntityValue production allows the definition +of a general entity consisting of a single explicit < in the literal +(e.g., <!ENTITY mylt "<">), it is strongly advised to avoid +this practice since any reference to that entity will cause a well-formedness +error.

+

2.4 Character Data and Markup

+ Text consists of intermingled character data and markup. [Definition: + Markup takes the form of start-tags, end-tags, empty-element tags, entity references, character +references, comments, CDATA section delimiters, document +type declarations, processing instructions, XML declarations, text declarations, +and any white space that is at the top level of the document entity (that +is, outside the document element and not inside any other markup).] +

+ [Definition: All text that is not markup +constitutes the character data of the document.] +

The ampersand character (&) and the left angle bracket (<) MUST NOT appear +in their literal form, except when used as markup delimiters, or +within a comment, a processing +instruction, or a CDATA section. + +If they are needed elsewhere, they MUST be escaped +using either numeric character references +or the strings " + &amp; + " and " + &lt; + " +respectively. The right angle bracket (>) may be represented using the string " + &gt; + ", +and MUST, for compatibility, be escaped +using either " + &gt; + " or a character reference when it +appears in the string " + ]]> + " in content, when +that string is not marking the end of a CDATA +section.

In the content of elements, character data is any string of characters +which does not contain the start-delimiter of any markup and does not include the CDATA-section-close +delimiter, " + ]]> + ". In a CDATA section, +character data is any string of characters not including the CDATA-section-close +delimiter, " + ]]> + ".

To allow attribute values to contain both single and double quotes, the +apostrophe or single-quote character (') may be represented as " + &apos; + ", +and the double-quote character (") as " + &quot; + ".

+
Character Data
[14]   CharData   ::=   [^<&]* - ([^<&]* ']]>' [^<&]*)
+

2.5 Comments

+ [Definition: + Comments may appear +anywhere in a document outside other markup; +in addition, they may appear within the document type declaration at places +allowed by the grammar. They are not part of the document's character +data; an XML processor MAY, but need not, make it possible for an +application to retrieve the text of comments. For +compatibility, the string " + -- + " (double-hyphen) +MUST NOT occur within comments.] Parameter +entity references MUST NOT be recognized within comments.

+
Comments
[15]   Comment   ::=   '<!--' ((Char - '-') | ('-' +(Char - '-')))* '-->'

An example of a comment:

<!-- declarations for <head> & <body> -->

Note +that the grammar does not allow a comment ending in --->. The +following example is not well-formed.

<!-- B+, B, or B--->
+

2.6 Processing Instructions

+ [Definition: + Processing instructions +(PIs) allow documents to contain instructions for applications.] +

+
Processing Instructions
[16]   PI   ::=   '<?' PITarget (S +(Char* - (Char* '?>' Char*)))? '?>'
[17]   PITarget   ::=    + Name - (('X' | 'x') ('M' | +'m') ('L' | 'l'))

PIs are not part of the document's character +data, but MUST be passed through to the application. The PI begins +with a target (PITarget) used to identify the application +to which the instruction is directed. The target names " + XML + ", " + xml + ", +and so on are reserved for standardization in this or future versions of this +specification. The XML Notation mechanism +may be used for formal declaration of PI targets. Parameter +entity references MUST NOT be recognized within processing instructions.

+

2.7 CDATA Sections

+ [Definition: + CDATA sections may occur anywhere character data may occur; they are used to escape blocks +of text containing characters which would otherwise be recognized as markup. +CDATA sections begin with the string " + <![CDATA[ + " +and end with the string " + ]]> + ":] +

+
CDATA Sections
[18]   CDSect   ::=    + CDStart + CData + CDEnd +
[19]   CDStart   ::=   '<![CDATA['
[20]   CData   ::=   (Char* - (Char* +']]>' Char*))
[21]   CDEnd   ::=   ']]>'

Within a CDATA section, only the CDEnd string is +recognized as markup, so that left angle brackets and ampersands may occur +in their literal form; they need not (and cannot) be escaped using " + &lt; + " +and " + &amp; + ". CDATA sections cannot nest.

An example of a CDATA section, in which " + <greeting> + " +and " + </greeting> + " are recognized as character data, not markup:

<![CDATA[<greeting>Hello, world!</greeting>]]>
+

2.8 Prolog and Document Type Declaration

+ [Definition: XML documents SHOULD +begin with an XML declaration which specifies the version of +XML being used.] For example, the following is a complete XML document, well-formed but not valid:

<?xml version="1.0"?>
+<greeting>Hello, world!</greeting>

and so is this:

<greeting>Hello, world!</greeting>

The function of the markup in an XML document is to describe its storage and +logical structure and to associate attribute +name-value pairs with its logical structures. XML provides a mechanism, the +document +type declaration, to define constraints on the logical structure +and to support the use of predefined storage units. [Definition: An XML document is valid if it has an associated +document type declaration and if the document complies with the constraints +expressed in it.] +

The document type declaration MUST appear before the first element +in the document.

+
Prolog
[22]   prolog   ::=    + XMLDecl? Misc* +(doctypedecl + Misc*)?
[23]   XMLDecl   ::=   '<?xml' VersionInfo + EncodingDecl? SDDecl? S? '?>'
[24]   VersionInfo   ::=    + S 'version' Eq +("'" VersionNum "'" | '"' VersionNum +'"')
[25]   Eq   ::=    + S? '=' S?
[26]   VersionNum   ::=   '1.' [0-9]+
[27]   Misc   ::=    + Comment | PI +| S +

Even though the VersionNum production matches + any version number of the form '1.x', XML 1.0 documents SHOULD NOT specify a version number other than '1.0'.

Note:

When an XML 1.0 processor encounters a document that specifies + a 1.x version number other than '1.0', it will process it as + a 1.0 document. This means that an XML 1.0 processor will accept + 1.x documents provided they do not use any non-1.0 features.

+ [Definition: The XML document +type declaration contains or points to markup +declarations that provide a grammar for a class of documents. This +grammar is known as a document type definition, or DTD. The document +type declaration can point to an external subset (a special kind of external entity) containing markup declarations, +or can contain the markup declarations directly in an internal subset, or +can do both. The DTD for a document consists of both subsets taken together.] +

+ [Definition: A markup declaration +is an element type declaration, an attribute-list declaration, an entity +declaration, or a notation declaration.] +These declarations may be contained in whole or in part within parameter +entities, as described in the well-formedness and validity constraints +below. For further +information, see 4 Physical Structures.

+
Document Type Definition
[28]   doctypedecl   ::=   '<!DOCTYPE' S + Name +(S + ExternalID)? S? +('[' intSubset ']' S?)? '>'[VC: Root Element Type]
[WFC: External Subset]
[28a]   DeclSep   ::=    + PEReference | S + [WFC: PE Between Declarations]
[28b]   intSubset   ::=   (markupdecl | DeclSep)*
[29]   markupdecl   ::=    + elementdecl | AttlistDecl | EntityDecl +| NotationDecl | PI | Comment + [VC: Proper Declaration/PE Nesting]
[WFC: PEs in Internal Subset]

Note +that it is possible to construct a well-formed document containing a doctypedecl +that neither points to an external subset nor contains an internal subset.

The markup declarations may be made up in whole or in part of the replacement text of parameter +entities. The productions later in this specification for individual +nonterminals (elementdecl, AttlistDecl, +and so on) describe the declarations after all the parameter +entities have been included.

Parameter +entity references are recognized anywhere in the DTD (internal and external +subsets and external parameter entities), except in literals, processing instructions, +comments, and the contents of ignored conditional sections (see 3.4 Conditional Sections). +They are also recognized in entity value literals. The use of parameter entities +in the internal subset is restricted as described below.

Validity constraint: Root Element Type

The Name +in the document type declaration MUST match the element type of the root element.

Validity constraint: Proper Declaration/PE Nesting

Parameter-entity replacement text + MUST be properly nested with markup declarations. That is to say, if either +the first character or the last character of a markup declaration (markupdecl +above) is contained in the replacement text for a parameter-entity +reference, both MUST be contained in the same replacement text.

Well-formedness constraint: PEs in Internal Subset

In +the internal DTD subset, parameter-entity references + MUST NOT occur within markup declarations; they may occur where markup declarations can occur. +(This does not apply to references that occur in external parameter entities +or to the external subset.)

Well-formedness constraint: External Subset

The external subset, if any, MUST match the production for extSubset.

Well-formedness constraint: PE Between Declarations

The replacement text of a parameter entity reference +in a DeclSep + MUST match the production extSubsetDecl.

Like the internal subset, the external subset and any external parameter +entities referenced +in a DeclSep + MUST consist of a series of +complete markup declarations of the types allowed by the non-terminal symbol markupdecl, interspersed with white space or parameter-entity references. However, portions of +the contents of the external subset or of these +external parameter entities may conditionally be ignored by using the conditional section construct; this is not +allowed in the internal subset but is +allowed in external parameter entities referenced in the internal subset.

+
External Subset
[30]   extSubset   ::=    + TextDecl? extSubsetDecl +
[31]   extSubsetDecl   ::=   ( markupdecl | conditionalSect | DeclSep)*

The external subset and external parameter entities also differ from the +internal subset in that in them, parameter-entity +references are permitted within markup declarations, +not only between markup declarations.

An example of an XML document with a document type declaration:

<?xml version="1.0"?>
+<!DOCTYPE greeting SYSTEM "hello.dtd">
+<greeting>Hello, world!</greeting>

The system identifier + " + hello.dtd + " +gives the address (a URI reference) of a DTD for the document.

The declarations can also be given locally, as in this example:

<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE greeting [
+  <!ELEMENT greeting (#PCDATA)>
+]>
+<greeting>Hello, world!</greeting>

If both the external and internal subsets are used, the internal subset +MUST be considered to occur before the external subset. +This has the effect that entity and attribute-list declarations in the internal +subset take precedence over those in the external subset.

+

2.9 Standalone Document Declaration

Markup declarations can affect the content of the document, as passed from +an XML processor to an application; examples +are attribute defaults and entity declarations. The standalone document declaration, +which may appear as a component of the XML declaration, signals whether or +not there are such declarations which appear external to the document +entity +or in parameter entities. [Definition: An external +markup declaration is defined as a markup declaration occurring in +the external subset or in a parameter entity (external or internal, the latter +being included because non-validating processors are not required to read +them).] +

+
Standalone Document Declaration
[32]   SDDecl   ::=    + S 'standalone' Eq +(("'" ('yes' | 'no') "'") | ('"' ('yes' | 'no') '"')) [VC: Standalone Document Declaration]

In a standalone document declaration, the value "yes" indicates +that there are no external markup declarations which +affect the information passed from the XML processor to the application. The +value "no" indicates that there are or may be such external +markup declarations. Note that the standalone document declaration only denotes +the presence of external declarations; the presence, in a document, +of references to external entities, when those entities are internally +declared, does not change its standalone status.

If there are no external markup declarations, the standalone document declaration +has no meaning. If there are external markup declarations but there is no +standalone document declaration, the value "no" is assumed.

Any XML document for which standalone="no" holds can be converted +algorithmically to a standalone document, which may be desirable for some +network delivery applications.

Validity constraint: Standalone Document Declaration

The +standalone document declaration MUST have the value "no" if +any external markup declarations contain declarations of:

  • attributes with default values, +if elements to which these attributes apply appear in the document without +specifications of values for these attributes, or

  • entities (other than amp, +lt, +gt, +apos, +quot), if references +to those entities appear in the document, or

  • attributes with +tokenized types, where the +attribute appears in the document with a value such that +normalization +will produce a different value from that which would be produced +in the absence of the declaration, or

  • element types with element content, +if white space occurs directly within any instance of those types.

An example XML declaration with a standalone document declaration:

<?xml version="1.0" standalone='yes'?>
+

2.10 White Space Handling

In editing XML documents, it is often convenient to use "white space" +(spaces, tabs, and blank lines) +to set apart the markup for greater readability. Such white space is typically +not intended for inclusion in the delivered version of the document. On the +other hand, "significant" white space that should be preserved +in the delivered version is common, for example in poetry and source code.

An XML processor + MUST always pass +all characters in a document that are not markup through to the application. +A validating XML processor + MUST also +inform the application which of these characters constitute white space appearing +in element content.

A special attribute named xml:space may be attached to an element to signal an intention that in that element, +white space should be preserved by applications. In valid documents, this +attribute, like any other, MUST be declared +if it is used. When declared, it MUST be given as an enumerated +type whose values +are one or both of "default" and "preserve". +For example:

<!ATTLIST poem  xml:space (default|preserve) 'preserve'>
+
+<!ATTLIST pre xml:space (preserve) #FIXED 'preserve'>

The value "default" signals that applications' default white-space +processing modes are acceptable for this element; the value "preserve" +indicates the intent that applications preserve all the white space. This +declared intent is considered to apply to all elements within the content +of the element where it is specified, unless overridden with +another instance of the xml:space attribute. This specification does not give meaning to any value of xml:space other than "default" and "preserve". It is an error for other values to be specified; the XML processor MAY report the error or MAY recover by ignoring the attribute specification or by reporting the (erroneous) value to the application. Applications may ignore or reject erroneous values.

The root element of any document is considered +to have signaled no intentions as regards application space handling, unless +it provides a value for this attribute or the attribute is declared with a +default value.

+

2.11 End-of-Line Handling

XML parsed entities are often stored +in computer files which, for editing convenience, are organized into lines. +These lines are typically separated by some combination of the characters +CARRIAGE RETURN (#xD) and LINE FEED (#xA).

To +simplify the tasks of applications, the +XML +processor + MUST behave as if it normalized all line breaks in external parsed +entities (including the document entity) on input, before parsing, by translating +both the two-character sequence #xD #xA and any #xD that is not followed by +#xA to a single #xA character.

+

2.12 Language Identification

In document processing, it is often useful to identify the natural or formal +language in which the content is written. A special attribute +named xml:lang may be inserted in documents to specify the language +used in the contents and attribute values of any element in an XML document. +In valid documents, this attribute, like any other, MUST be declared +if it is used. The +values of the attribute are language identifiers as defined by [IETF BCP 47], Tags +for the Identification of Languages; in addition, the empty string may be specified.

(Productions 33 through 38 have been removed.)

For example:

<p xml:lang="en">The quick brown fox jumps over the lazy dog.</p>
+<p xml:lang="en-GB">What colour is it?</p>
+<p xml:lang="en-US">What color is it?</p>
+<sp who="Faust" desc='leise' xml:lang="de">
+  <l>Habe nun, ach! Philosophie,</l>
+  <l>Juristerei, und Medizin</l>
+  <l>und leider auch Theologie</l>
+  <l>durchaus studiert mit heißem Bemüh'n.</l>
+</sp>

The language specified by xml:lang applies to the element where it is specified + (including the values of its attributes), and to all elements in its content unless + overridden with another instance of xml:lang. In particular, the empty value of xml:lang is used on an element B to override + a specification of xml:lang on an enclosing element A, without specifying another language. Within B, + it is considered that there is no language information available, just as if xml:lang had not been specified + on B or any of its ancestors. Applications determine which of an element's attribute values + and which parts of its character content, if any, are treated as language-dependent values described by xml:lang.

Note:

Language information may also be provided by external transport protocols (e.g. HTTP or + MIME). When available, this information may be used by XML applications, but the more local + information provided by xml:lang should be considered to override it. +

A simple declaration for xml:lang might take the form

xml:lang CDATA #IMPLIED

but specific default values may also be given, if appropriate. In a collection +of French poems for English students, with glosses and notes in English, the xml:lang +attribute might be declared this way:

<!ATTLIST poem   xml:lang CDATA 'fr'>
+<!ATTLIST gloss  xml:lang CDATA 'en'>
+<!ATTLIST note   xml:lang CDATA 'en'>
+

3 Logical Structures

+ [Definition: Each XML +document contains one or more elements, the boundaries +of which are either delimited by start-tags +and end-tags, or, for empty +elements, by an empty-element tag. Each +element has a type, identified by name, sometimes called its "generic +identifier" (GI), and may have a set of attribute specifications.] +Each attribute specification has a name +and a value.

+
Element
[39]   element   ::=    + EmptyElemTag +
| STag + content + ETag + [WFC: Element Type Match]
[VC: Element Valid]

This specification does not constrain the + application semantics, use, or (beyond syntax) +names of the element types and attributes, except that names beginning with +a match to (('X'|'x')('M'|'m')('L'|'l')) are reserved for standardization +in this or future versions of this specification.

Well-formedness constraint: Element Type Match

The Name +in an element's end-tag MUST match the element type in the start-tag.

Validity constraint: Element Valid

An element is valid +if there is a declaration matching elementdecl +where the Name matches the element type, and one of +the following holds:

  1. The declaration matches EMPTY and the element has no content (not even entity +references, comments, PIs or white space).

  2. The declaration matches children and the +sequence of child elements belongs +to the language generated by the regular expression in the content model, +with optional white space, comments and +PIs (i.e. markup matching production [27] Misc) between the +start-tag and the first child element, between child elements, or between +the last child element and the end-tag. Note that a CDATA section containing +only white space or a reference +to an entity whose replacement text is character references expanding to white +space do not +match the nonterminal S, and +hence cannot appear in these positions; however, a +reference to an internal entity with a literal value consisting of character +references expanding to white space does match S, since its +replacement text is the white space resulting from expansion of the character +references.

  3. The declaration matches Mixed, and the content +(after replacing +any entity references with their replacement text) consists of +character data +(including CDATA sections), +comments, PIs and child elements whose types match names in the +content model.

  4. The declaration matches ANY, and the content (after replacing +any entity references with their replacement text) +consists of character data, CDATA +sections, comments, PIs + and child elements +whose types have been declared.

+

3.1 Start-Tags, End-Tags, and Empty-Element Tags

+ [Definition: The beginning of every non-empty +XML element is marked by a start-tag.] +

+
Start-tag
[40]   STag   ::=   '<' Name (S + Attribute)* S? '>'[WFC: Unique Att Spec]
[41]   Attribute   ::=    + Name + Eq + AttValue + [VC: Attribute Value Type]
[WFC: No External Entity References]
[WFC: No < in Attribute Values]

The Name in the start- and end-tags gives the element's type. [Definition: The Name-AttValue +pairs are referred to as the attribute specifications of the +element], [Definition: with the Name in each pair referred to as the attribute name + ] +and [Definition: the content of the AttValue (the text between the ' or " +delimiters) as the attribute value.] Note +that the order of attribute specifications in a start-tag or empty-element +tag is not significant.

Well-formedness constraint: Unique Att Spec

An attribute name +MUST NOT appear more than once in the same start-tag or empty-element tag.

Validity constraint: Attribute Value Type

The attribute MUST +have been declared; the value MUST be of the type declared for it. (For attribute +types, see 3.3 Attribute-List Declarations.)

Well-formedness constraint: No External Entity References

Attribute +values MUST NOT contain direct or indirect entity references to external entities.

Well-formedness constraint: No < in Attribute Values

The replacement text of any entity +referred to directly or indirectly in an attribute value MUST NOT contain a <.

An example of a start-tag:

<termdef id="dt-dog" term="dog">

+ [Definition: The end of every element that begins +with a start-tag MUST be marked by an end-tag containing a name +that echoes the element's type as given in the start-tag:] +

+
End-tag
[42]   ETag   ::=   '</' Name + S? +'>'

An example of an end-tag:

</termdef>

+ [Definition: The text +between the start-tag and end-tag is called the element's content:] +

+
Content of Elements
[43]   content   ::=    + CharData? ((element +| Reference | CDSect +| PI | Comment) CharData?)*

+ [Definition: An element +with no content is said to be empty.] The representation +of an empty element is either a start-tag immediately followed by an end-tag, +or an empty-element tag. [Definition: An empty-element +tag takes a special form:] +

+
Tags for Empty Elements
[44]   EmptyElemTag   ::=   '<' Name (S + Attribute)* S? '/>'[WFC: Unique Att Spec]

Empty-element tags may be used for any element which has no content, whether +or not it is declared using the keyword EMPTY. For +interoperability, the empty-element tag SHOULD +be used, and SHOULD only be used, for elements which are declared +EMPTY.

Examples of empty elements:

<IMG align="left"
+ src="http://www.w3.org/Icons/WWW/w3c_home" />
+<br></br>
+<br/>
+

3.2 Element Type Declarations

The element structure of an XML document may, for validation +purposes, be constrained using element type and attribute-list declarations. +An element type declaration constrains the element's content.

Element type declarations often constrain which element types can appear +as children of the element. At user +option, an XML processor MAY issue a warning when a declaration mentions an +element type for which no declaration is provided, but this is not an error.

+ [Definition: An element +type declaration takes the form:] +

+
Element Type Declaration
[45]   elementdecl   ::=   '<!ELEMENT' S + Name + S + contentspec + S? +'>'[VC: Unique Element Type Declaration]
[46]   contentspec   ::=   'EMPTY' | 'ANY' | Mixed +| children +

where the Name gives the element type being declared.

Validity constraint: Unique Element Type Declaration

An element type MUST NOT be declared more than once.

Examples of element type declarations:

<!ELEMENT br EMPTY>
+<!ELEMENT p (#PCDATA|emph)* >
+<!ELEMENT %name.para; %content.para; >
+<!ELEMENT container ANY>
+

3.2.1 Element Content

+ [Definition: An element type has element content when elements +of that type MUST contain only child +elements (no character data), optionally separated by white space (characters +matching the nonterminal S).] + [Definition: In this case, the constraint includes a content +model, a simple grammar governing the allowed types of the +child elements and the order in which they are allowed to appear.] +The grammar is built on content particles (cps), which +consist of names, choice lists of content particles, or sequence lists of +content particles:

+
Element-content Models
[47]   children   ::=   (choice | seq) +('?' | '*' | '+')?
[48]   cp   ::=   (Name | choice +| seq) ('?' | '*' | '+')?
[49]   choice   ::=   '(' S? cp ( S? '|' S? cp )+ S? ')'[VC: Proper Group/PE Nesting]
[50]   seq   ::=   '(' S? cp ( S? ',' S? cp )* S? ')'[VC: Proper Group/PE Nesting]

where each Name is the type of an element which +may appear as a child. Any content +particle in a choice list may appear in the element +content at the location where the choice list appears in the grammar; +content particles occurring in a sequence list MUST each appear in the element content in the order given in the list. +The optional character following a name or list governs whether the element +or the content particles in the list may occur one or more (+), +zero or more (*), or zero or one times (?). The +absence of such an operator means that the element or content particle MUST +appear exactly once. This syntax and meaning are identical to those used in +the productions in this specification.

The content of an element matches a content model if and only if it is +possible to trace out a path through the content model, obeying the sequence, +choice, and repetition operators and matching each element in the content +against an element type in the content model. For +compatibility, it is an error if the content model +allows an element to match more than one occurrence of an element type in the +content model. For more information, see E Deterministic Content Models.

Validity constraint: Proper Group/PE Nesting

Parameter-entity replacement text + MUST be properly nested with parenthesized +groups. That is to say, if either of the opening or closing parentheses in +a choice, seq, or Mixed +construct is contained in the replacement text for a parameter +entity, both MUST be contained in the same replacement text.

+ For interoperability, if a parameter-entity reference +appears in a choice, seq, or Mixed construct, its replacement text SHOULD contain at +least one non-blank character, and neither the first nor last non-blank character +of the replacement text SHOULD be a connector (| or ,).

Examples of element-content models:

<!ELEMENT spec (front, body, back?)>
+<!ELEMENT div1 (head, (p | list | note)*, div2*)>
+<!ELEMENT dictionary-body (%div.mix; | %dict.mix;)*>
+

3.2.2 Mixed Content

+ [Definition: An element type +has mixed content when elements of that type may contain character +data, optionally interspersed with child +elements.] In this case, the types of the child elements may be constrained, +but not their order or their number of occurrences:

+
Mixed-content Declaration
[51]   Mixed   ::=   '(' S? '#PCDATA' (S? +'|' S? Name)* S? +')*'
| '(' S? '#PCDATA' S? ')' [VC: Proper Group/PE Nesting]
[VC: No Duplicate Types]

where the Names give the types of elements that +may appear as children. The +keyword #PCDATA derives historically from the term "parsed +character data." +

Validity constraint: No Duplicate Types

The +same name MUST NOT appear more than once in a single mixed-content declaration.

Examples of mixed content declarations:

<!ELEMENT p (#PCDATA|a|ul|b|i|em)*>
+<!ELEMENT p (#PCDATA | %font; | %phrase; | %special; | %form;)* >
+<!ELEMENT b (#PCDATA)>
+

3.3 Attribute-List Declarations

+ Attributes are used to associate name-value +pairs with elements. Attribute specifications +MUST NOT appear outside of start-tags and empty-element tags; thus, the productions used to +recognize them appear in 3.1 Start-Tags, End-Tags, and Empty-Element Tags. Attribute-list declarations +may be used:

  • To define the set of attributes pertaining to a given element type.

  • To establish type constraints for these attributes.

  • To provide default values for +attributes.

+ [Definition: + Attribute-list +declarations specify the name, data type, and default value (if any) +of each attribute associated with a given element type:] +

+
Attribute-list Declaration
[52]   AttlistDecl   ::=   '<!ATTLIST' S + Name + AttDef* S? '>'
[53]   AttDef   ::=    + S + Name + S + AttType + S + DefaultDecl +

The Name in the AttlistDecl +rule is the type of an element. At user option, an XML processor MAY issue +a warning if attributes are declared for an element type not itself declared, +but this is not an error. The Name in the AttDef +rule is the name of the attribute.

When more than one AttlistDecl is provided +for a given element type, the contents of all those provided are merged. When +more than one definition is provided for the same attribute of a given element +type, the first declaration is binding and later declarations are ignored. For interoperability, writers of DTDs may choose +to provide at most one attribute-list declaration for a given element type, +at most one attribute definition for a given attribute name in an attribute-list +declaration, and at least one attribute definition in each attribute-list +declaration. For interoperability, an XML processor MAY at user option +issue a warning when more than one attribute-list declaration is provided +for a given element type, or more than one attribute definition is provided +for a given attribute, but this is not an error.

+

3.3.1 Attribute Types

XML attribute types are of three kinds: a string type, a set of tokenized +types, and enumerated types. The string type may take any literal string as +a value; the tokenized types are more constrained. +The validity constraints noted in the grammar are applied after the attribute +value has been normalized as described in 3.3.3 Attribute-Value Normalization.

+
Attribute Types
[54]   AttType   ::=    + StringType | TokenizedType +| EnumeratedType +
[55]   StringType   ::=   'CDATA'
[56]   TokenizedType   ::=   'ID'[VC: ID]
[VC: One ID per Element Type]
[VC: ID Attribute Default]
| 'IDREF'[VC: IDREF]
| 'IDREFS'[VC: IDREF]
| 'ENTITY'[VC: Entity Name]
| 'ENTITIES'[VC: Entity Name]
| 'NMTOKEN'[VC: Name Token]
| 'NMTOKENS'[VC: Name Token]

Validity constraint: ID

Values of type ID + MUST match the Name production. A name MUST NOT appear more than once +in an XML document as a value of this type; i.e., ID values MUST uniquely +identify the elements which bear them.

Validity constraint: One ID per Element Type

An element type MUST NOT have more than one ID attribute specified.

Validity constraint: ID Attribute Default

An ID attribute +MUST have a declared default of #IMPLIED or #REQUIRED.

Validity constraint: IDREF

Values of type IDREF + MUST +match the Name production, and values of type IDREFS + MUST match Names; each Name + MUST match the value of an ID attribute on some element in the XML document; +i.e. IDREF values MUST match the value of some ID attribute.

Validity constraint: Entity Name

Values of type ENTITY + MUST match the Name production, values of type ENTITIES + MUST match Names; each Name + MUST match the name of an unparsed entity +declared in the DTD.

Validity constraint: Name Token

Values of type NMTOKEN + MUST match the Nmtoken production; values of type NMTOKENS + MUST match Nmtokens.

+ [Definition: + Enumerated attributes + have a list of allowed values in their declaration + ]. They MUST take one of those values. There are two kinds of enumerated attribute types:

+
Enumerated Attribute Types
[57]   EnumeratedType   ::=    + NotationType +| Enumeration +
[58]   NotationType   ::=   'NOTATION' S '(' S? Name (S? '|' S? Name)* S? ')' [VC: Notation Attributes]
[VC: One Notation Per Element Type]
[VC: No Notation on Empty Element]
[VC: No Duplicate Tokens]
[59]   Enumeration   ::=   '(' S? Nmtoken +(S? '|' S? Nmtoken)* S? ')'[VC: Enumeration]
[VC: No Duplicate Tokens]

A NOTATION attribute identifies a notation, +declared in the DTD with associated system and/or public identifiers, to be +used in interpreting the element to which the attribute is attached.

Validity constraint: Notation Attributes

Values of this type +MUST match one of the notation names +included in the declaration; all notation names in the declaration MUST be +declared.

Validity constraint: One Notation Per Element Type

An element type MUST NOT have more than one NOTATION +attribute specified.

Validity constraint: No Notation on Empty Element

+ For compatibility, +an attribute of type NOTATION + MUST NOT be declared on an element +declared EMPTY.

Validity constraint: No Duplicate Tokens

The notation names in a single NotationType +attribute declaration, as well as the NmTokens in a single +Enumeration attribute declaration, MUST all be distinct.

Validity constraint: Enumeration

Values of this type MUST match +one of the Nmtoken tokens in the declaration.

+ For interoperability, the same Nmtoken + SHOULD NOT occur more than once in the enumerated +attribute types of a single element type.

+

3.3.2 Attribute Defaults

An attribute declaration provides information +on whether the attribute's presence is REQUIRED, and if not, how an XML processor +is to react if a declared attribute is absent in a document.

+
Attribute Defaults
[60]   DefaultDecl   ::=   '#REQUIRED' | '#IMPLIED'
| (('#FIXED' S)? AttValue)[VC: Required Attribute]
[VC: Attribute Default Value Syntactically Correct]
[WFC: No < in Attribute Values]
[VC: Fixed Attribute Default]
[WFC: No External Entity References]

In an attribute declaration, #REQUIRED means that the attribute +MUST always be provided, #IMPLIED that no default value is provided. + + [Definition: If +the declaration is neither #REQUIRED nor #IMPLIED, then +the AttValue value contains the declared default +value; the #FIXED keyword states that the attribute MUST always have +the default value. +When an XML processor encounters +an element +without a specification for an attribute for which it has read a default +value declaration, it MUST report the attribute with the declared default +value to the application.] +

Validity constraint: Required Attribute

If the default +declaration is the keyword #REQUIRED, then the attribute MUST be +specified for all elements of the type in the attribute-list declaration.

Validity constraint: Attribute Default Value Syntactically Correct

The declared default value MUST meet the syntactic +constraints of the declared attribute type. That is, the default value of an attribute: +

Note that only the +syntactic constraints of the type are required here; other constraints (e.g. +that the value be the name of a declared unparsed entity, for an attribute of +type ENTITY) will be reported by a validating +parser only if an element without a specification for this attribute +actually occurs.

Validity constraint: Fixed Attribute Default

If an attribute +has a default value declared with the #FIXED keyword, instances of +that attribute MUST match the default value.

Examples of attribute-list declarations:

<!ATTLIST termdef
+          id      ID      #REQUIRED
+          name    CDATA   #IMPLIED>
+<!ATTLIST list
+          type    (bullets|ordered|glossary)  "ordered">
+<!ATTLIST form
+          method  CDATA   #FIXED "POST">
+

3.3.3 Attribute-Value Normalization

Before the value of an attribute is passed to the application or checked +for validity, the XML processor MUST normalize the attribute value by applying +the algorithm below, or by using some other method such that the value passed +to the application is the same as that produced by the algorithm.

  1. All line breaks MUST have been normalized on input to #xA as described +in 2.11 End-of-Line Handling, so the rest of this algorithm operates +on text normalized in this way.

  2. Begin with a normalized value consisting of the empty string.

  3. For each character, entity reference, or character reference in the +unnormalized attribute value, beginning with the first and continuing to the +last, do the following:

    • For a character reference, append the referenced character to the +normalized value.

    • For an entity reference, recursively apply step 3 of this algorithm +to the replacement text of the entity.

    • For a white space character (#x20, #xD, #xA, #x9), append a space +character (#x20) to the normalized value.

    • For another character, append the character to the normalized value.

If the attribute type is not CDATA, then the XML processor MUST further +process the normalized attribute value by discarding any leading and trailing +space (#x20) characters, and by replacing sequences of space (#x20) characters +by a single space (#x20) character.

Note that if the unnormalized attribute value contains a character reference +to a white space character other than space (#x20), the normalized value contains +the referenced character itself (#xD, #xA or #x9). This contrasts with the +case where the unnormalized value contains a white space character (not a +reference), which is replaced with a space character (#x20) in the normalized +value and also contrasts with the case where the unnormalized value contains +an entity reference whose replacement text contains a white space character; +being recursively processed, the white space character is replaced with a +space character (#x20) in the normalized value.

All attributes for which no declaration has been read SHOULD be treated +by a non-validating processor as if declared CDATA.

It is an error if an attribute +value contains a reference to an +entity for which no declaration has been read.

Following are examples of attribute normalization. Given the following +declarations:

<!ENTITY d "&#xD;">
+<!ENTITY a "&#xA;">
+<!ENTITY da "&#xD;&#xA;">

the attribute specifications in the left column below would be normalized +to the character sequences of the middle column if the attribute a +is declared NMTOKENS and to those of the right columns if a +is declared CDATA.

Attribute specificationa is NMTOKENSa is CDATA
+ 
a="
+
+xyz"
+ 		+ 
x y z
+ 		+ 
#x20 #x20 x y z
+
+ 
a="&d;&d;A&a;&#x20;&a;B&da;"
+ 		+ 
A #x20 B
+ 		+ 
#x20 #x20 A #x20 #x20 #x20 B #x20 #x20
+
+ 
a=
+"&#xd;&#xd;A&#xa;&#xa;B&#xd;&#xa;"
+ 		+ 
#xD #xD A #xA #xA B #xD #xA
+ 		+ 
#xD #xD A #xA #xA B #xD #xA
+

Note that the last example is invalid (but well-formed) if a +is declared to be of type NMTOKENS.

+

3.4 Conditional Sections

+ [Definition: + Conditional +sections are portions of the document type +declaration external subset or +of external parameter entities which are included in, or excluded from, +the logical structure of the DTD based on the keyword which governs them.] +

+
Conditional Section
[61]   conditionalSect   ::=    + includeSect | ignoreSect +
[62]   includeSect   ::=   '<![' S? 'INCLUDE' S? '[' extSubsetDecl +']]>' [VC: Proper Conditional Section/PE Nesting]
[63]   ignoreSect   ::=   '<![' S? 'IGNORE' S? '[' ignoreSectContents* +']]>'[VC: Proper Conditional Section/PE Nesting]
[64]   ignoreSectContents   ::=    + Ignore ('<![' ignoreSectContents ']]>' Ignore)*
[65]   Ignore   ::=    + Char* - (Char* +('<![' | ']]>') Char*)

Validity constraint: Proper Conditional Section/PE Nesting

If any of the "<![", +"[", or "]]>" of a conditional section is contained +in the replacement text for a parameter-entity reference, all of them MUST +be contained in the same replacement text.

Like the internal and external DTD subsets, a conditional section may contain +one or more complete declarations, comments, processing instructions, or nested +conditional sections, intermingled with white space.

If the keyword of the conditional section is INCLUDE, then the +contents of the conditional section MUST be processed as part of the DTD. If the keyword of +the conditional section is IGNORE, then the contents of the conditional +section MUST NOT be processed as part of the DTD. +If a conditional section with a keyword of INCLUDE occurs within +a larger conditional section with a keyword of IGNORE, both the outer +and the inner conditional sections MUST be ignored. The contents +of an ignored conditional section MUST be parsed by ignoring all characters after +the "[" following the keyword, except conditional section starts +"<![" and ends "]]>", until the matching conditional +section end is found. Parameter entity references MUST NOT be recognized in this +process.

If the keyword of the conditional section is a parameter-entity reference, +the parameter entity MUST be replaced by its content before the processor +decides whether to include or ignore the conditional section.

An example:

<!ENTITY % draft 'INCLUDE' >
+<!ENTITY % final 'IGNORE' >
+
+<![%draft;[
+<!ELEMENT book (comments*, title, body, supplements?)>
+]]>
+<![%final;[
+<!ELEMENT book (title, body, supplements?)>
+]]>
+

4 Physical Structures

+ [Definition: An XML document may consist of one +or many storage units. These +are called entities; they all have content and are +all (except for the document entity and +the external DTD subset) identified by +entity name.] Each XML document has one entity +called the document entity, which serves +as the starting point for the XML processor +and may contain the whole document.

Entities may be either parsed or unparsed. [Definition: The contents of a parsed +entity are referred to as its replacement +text; this text is considered an +integral part of the document.] +

+ [Definition: An unparsed entity +is a resource whose contents may or may not be text, +and if text, may +be other than XML. Each unparsed entity has an associated notation, identified by name. Beyond a requirement +that an XML processor make the identifiers for the entity and notation available +to the application, XML places no constraints on the contents of unparsed +entities.] +

Parsed entities are invoked by name using entity references; unparsed entities +by name, given in the value of ENTITY or ENTITIES attributes.

+ [Definition: + General entities +are entities for use within the document content. In this specification, general +entities are sometimes referred to with the unqualified term entity +when this leads to no ambiguity.] + [Definition: + Parameter +entities are parsed entities for use within the DTD.] +These two types of entities use different forms of reference and are recognized +in different contexts. Furthermore, they occupy different namespaces; a parameter +entity and a general entity with the same name are two distinct entities.

+

4.1 Character and Entity References

+ [Definition: A character +reference refers to a specific character in the ISO/IEC 10646 character +set, for example one not directly accessible from available input devices.] +

+
Character Reference
[66]   CharRef   ::=   '&#' [0-9]+ ';'
| '&#x' [0-9a-fA-F]+ ';'[WFC: Legal Character]

Well-formedness constraint: Legal Character

Characters referred +to using character references MUST match the production for Char.

If the character reference begins with " + &#x + ", +the digits and letters up to the terminating ; provide a hexadecimal +representation of the character's code point in ISO/IEC 10646. If it begins +just with " + &# + ", the digits up to the terminating ; +provide a decimal representation of the character's code point.

+ [Definition: An entity reference +refers to the content of a named entity.] + [Definition: References to parsed general entities use +ampersand (&) and semicolon (;) as delimiters.] + [Definition: + Parameter-entity references +use percent-sign (%) and semicolon (;) as delimiters.] +

+
Entity Reference
[67]   Reference   ::=    + EntityRef | CharRef +
[68]   EntityRef   ::=   '&' Name ';'[WFC: Entity Declared]
[VC: Entity Declared]
[WFC: Parsed Entity]
[WFC: No Recursion]
[69]   PEReference   ::=   '%' Name ';'[VC: Entity Declared]
[WFC: No Recursion]
[WFC: In DTD]

Well-formedness constraint: Entity Declared

In a document +without any DTD, a document with only an internal DTD subset which contains +no parameter entity references, or a document with " + standalone='yes' + ", for +an entity reference that does not occur within the external subset or a parameter +entity, the Name given in the entity reference MUST + match that in an entity +declaration that does not occur within the external subset or a +parameter entity, except that well-formed documents need not declare +any of the following entities: amp, +lt, +gt, +apos, +quot. The +declaration of a general entity MUST precede any reference to it which appears +in a default value in an attribute-list declaration.

Note that non-validating processors are not +obligated to read and process entity declarations occurring in parameter entities or in +the external subset; for such documents, +the rule that an entity must be declared is a well-formedness constraint only +if standalone='yes'.

Validity constraint: Entity Declared

In a document with an external subset or parameter entity references, + if the document is not standalone (either "standalone='no'" + is specified or there is no standalone declaration), then +the Name given in the entity reference MUST + match that in an entity +declaration. For interoperability, valid documents SHOULD declare +the entities amp, +lt, +gt, +apos, +quot, in the form specified in 4.6 Predefined Entities. +The declaration of a parameter entity MUST precede any reference to it. Similarly, +the declaration of a general entity MUST precede any attribute-list +declaration containing a default value with a direct or indirect reference +to that general entity.

Well-formedness constraint: Parsed Entity

An entity reference MUST +NOT contain the name of an unparsed entity. +Unparsed entities may be referred to only in attribute +values declared to be of type ENTITY or ENTITIES.

Well-formedness constraint: No Recursion

A parsed entity MUST NOT contain a recursive reference to itself, either directly or indirectly.

Well-formedness constraint: In DTD

Parameter-entity references MUST NOT appear outside + the DTD.

Examples of character and entity references:

Type <key>less-than</key> (&#x3C;) to save options.
+This document was prepared on &docdate; and
+is classified &security-level;.

Example of a parameter-entity reference:

<!-- declare the parameter entity "ISOLat2"... -->
+<!ENTITY % ISOLat2
+         SYSTEM "http://www.xml.com/iso/isolat2-xml.entities" >
+<!-- ... now reference it. -->
+%ISOLat2;
+

4.2 Entity Declarations

+ [Definition: Entities are declared +thus:] +

+
Entity Declaration
[70]   EntityDecl   ::=    + GEDecl + | PEDecl +
[71]   GEDecl   ::=   '<!ENTITY' S + Name + S + EntityDef + S? +'>'
[72]   PEDecl   ::=   '<!ENTITY' S '%' S + Name + S + PEDef + S? '>'
[73]   EntityDef   ::=    + EntityValue + | (ExternalID + NDataDecl?)
[74]   PEDef   ::=    + EntityValue | ExternalID +

The Name identifies the entity in an entity +reference or, in the case of an unparsed entity, in the value of +an ENTITY or ENTITIES attribute. If the same entity is declared +more than once, the first declaration encountered is binding; at user option, +an XML processor MAY issue a warning if entities are declared multiple times.

+

4.2.1 Internal Entities

+ [Definition: If the +entity definition is an EntityValue, the defined +entity is called an internal entity. There is no separate physical +storage object, and the content of the entity is given in the declaration.] +Note that some processing of entity and character references in the literal entity value may be required to produce +the correct replacement text: see 4.5 Construction of Entity Replacement Text.

An internal entity is a parsed entity.

Example of an internal entity declaration:

<!ENTITY Pub-Status "This is a pre-release of the
+ specification.">
+

4.2.2 External Entities

+ [Definition: If the entity is not internal, +it is an external entity, declared as follows:] +

+
External Entity Declaration
[75]   ExternalID   ::=   'SYSTEM' S + SystemLiteral +
| 'PUBLIC' S + PubidLiteral + S + SystemLiteral +
[76]   NDataDecl   ::=    + S 'NDATA' S + Name + [VC: Notation Declared]

If the NDataDecl is present, this is a general unparsed entity; otherwise it is a parsed entity.

Validity constraint: Notation Declared

The Name + MUST match the declared name of a notation.

+ [Definition: The SystemLiteral is called the entity's system +identifier. It is meant to be converted to a URI reference +(as defined in [IETF RFC 3986]), +as part of the +process of dereferencing it to obtain input for the XML processor to construct the +entity's replacement text.] It is an error for a fragment identifier +(beginning with a # character) to be part of a system identifier. +Unless otherwise provided by information outside the scope of this specification +(e.g. a special XML element type defined by a particular DTD, or a processing +instruction defined by a particular application specification), relative URIs +are relative to the location of the resource within which the entity declaration +occurs. This is defined to +be the external entity containing the '<' which starts the declaration, at the +point when it is parsed as a declaration. +A URI might thus be relative to the document +entity, to the entity containing the external +DTD subset, or to some other external parameter +entity. Attempts to +retrieve the resource identified by a URI may be redirected at the parser +level (for example, in an entity resolver) or below (at the protocol level, +for example, via an HTTP Location: header). In the absence of additional +information outside the scope of this specification within the resource, +the base URI of a resource is always the URI of the actual resource returned. +In other words, it is the URI of the resource retrieved after all redirection +has occurred.

System +identifiers (and other XML strings meant to be used as URI references) may contain +characters that, according to [IETF RFC 3986], +must be escaped before a URI can be used to retrieve the referenced resource. The +characters to be escaped are the control characters #x0 to #x1F and #x7F (most of +which cannot appear in XML), space #x20, the delimiters '<' #x3C, '>' #x3E and +'"' #x22, the unwise characters '{' #x7B, '}' #x7D, '|' #x7C, '\' #x5C, '^' #x5E and +'`' #x60, as well as all characters above #x7F. Since escaping is not always a fully +reversible process, it MUST be performed only when absolutely necessary and as late +as possible in a processing chain. In particular, neither the process of converting +a relative URI to an absolute one nor the process of passing a URI reference to a +process or software component responsible for dereferencing it SHOULD trigger escaping. +When escaping does occur, it MUST be performed as follows:

  1. Each character to be escaped is represented in UTF-8 [Unicode] +as one or more bytes.

  2. The resulting bytes are escaped with +the URI escaping mechanism (that is, converted to % + HH, +where HH is the hexadecimal notation of the byte value).

  3. The original character is replaced by the resulting character sequence.

Note:

In a future edition of this specification, the XML Core Working Group intends to replace the preceding paragraph + and list of steps with a normative reference to an upcoming revision of IETF RFC 3987, which will define + "Legacy Extended IRIs (LEIRIs)". When this revision is available, it is the intent of the XML Core WG to use it to replace + language similar to the above in any future revisions of XML-related specifications under its purview.

+ [Definition: In addition to a system +identifier, an external identifier may include a public identifier.] +An XML processor attempting to retrieve the entity's content may use +any combination of +the public and system identifiers as well as additional information outside the +scope of this specification to try to generate an alternative URI reference. +If the processor is unable to do so, it MUST use the URI +reference specified in the system literal. Before a match is attempted, +all strings of white space in the public identifier MUST be normalized to +single space characters (#x20), and leading and trailing white space MUST +be removed.

Examples of external entity declarations:

<!ENTITY open-hatch
+         SYSTEM "http://www.textuality.com/boilerplate/OpenHatch.xml">
+<!ENTITY open-hatch
+         PUBLIC "-//Textuality//TEXT Standard open-hatch boilerplate//EN"
+         "http://www.textuality.com/boilerplate/OpenHatch.xml">
+<!ENTITY hatch-pic
+         SYSTEM "../grafix/OpenHatch.gif"
+         NDATA gif >
+

4.3 Parsed Entities

+

4.3.1 The Text Declaration

External parsed entities SHOULD each begin with a text declaration.

+
Text Declaration
[77]   TextDecl   ::=   '<?xml' VersionInfo? EncodingDecl + S? '?>'

The text declaration MUST be provided literally, not by reference + to a parsed entity. The text declaration + MUST NOT appear at any + position other than the beginning of an external parsed entity. The text declaration + in an external parsed entity is not considered part of its replacement text.

+

4.3.2 Well-Formed Parsed Entities

The document entity is well-formed if it matches the production labeled document. An external general parsed entity is well-formed +if it matches the production labeled extParsedEnt. All +external parameter entities are well-formed by definition.

Note:

Only parsed entities that are referenced directly or indirectly within the document are required to be well-formed.

+
Well-Formed External Parsed Entity
[78]   extParsedEnt   ::=    + TextDecl? content +

An internal general parsed entity is well-formed if its replacement text +matches the production labeled content. All internal +parameter entities are well-formed by definition.

A consequence of well-formedness in general +entities is that the logical and physical +structures in an XML document are properly nested; no start-tag, end-tag, empty-element tag, element, comment, processing instruction, character +reference, or entity reference +can begin in one entity and end in another.

+

4.3.3 Character Encoding in Entities

Each external parsed entity in an XML document may use a different encoding +for its characters. All XML processors MUST be able to read entities in both +the UTF-8 and UTF-16 encodings. The terms "UTF-8" +and "UTF-16" in this specification do not apply to + +related character encodings, including but not limited to UTF-16BE, UTF-16LE, or CESU-8.

Entities encoded in UTF-16 MUST and entities +encoded in UTF-8 MAY begin with the Byte Order Mark described by +Annex H of [ISO/IEC 10646:2000], section +16.8 of [Unicode] +(the ZERO WIDTH NO-BREAK SPACE character, #xFEFF). This is an encoding signature, +not part of either the markup or the character data of the XML document. XML +processors MUST be able to use this character to differentiate between UTF-8 +and UTF-16 encoded documents.

If the replacement text of an external entity is to + begin with the character U+FEFF, and no text declaration + is present, then a Byte Order Mark MUST be present, + whether the entity is encoded in UTF-8 or UTF-16.

Although an XML processor is required to read only entities in the UTF-8 +and UTF-16 encodings, it is recognized that other encodings are used around +the world, and it may be desired for XML processors to read entities that +use them. In +the absence of external character encoding information (such as MIME headers), +parsed entities which are stored in an encoding other than UTF-8 or UTF-16 +MUST begin with a text declaration (see 4.3.1 The Text Declaration) containing +an encoding declaration:

+
Encoding Declaration
[80]   EncodingDecl   ::=    + S 'encoding' Eq +('"' EncName '"' | "'" EncName +"'" )
[81]   EncName   ::=   [A-Za-z] ([A-Za-z0-9._] | '-')*/* Encoding +name contains only Latin characters */

In the document entity, the encoding +declaration is part of the XML declaration. +The EncName is the name of the encoding used.

In an encoding declaration, the values " + UTF-8 + ", " + UTF-16 + ", +" + ISO-10646-UCS-2 + ", and " + ISO-10646-UCS-4 + " + SHOULD be used +for the various encodings and transformations of Unicode / ISO/IEC 10646, +the values " + ISO-8859-1 + ", " + ISO-8859-2 + ", +... " + ISO-8859- + n + " (where n +is the part number) SHOULD be used for the parts of ISO 8859, and +the values " + ISO-2022-JP + ", " + Shift_JIS + ", +and " + EUC-JP + " + SHOULD be used for the various encoded +forms of JIS X-0208-1997. It +is RECOMMENDED that character encodings registered (as charsets) +with the Internet Assigned Numbers Authority [IANA-CHARSETS], +other than those just listed, be referred to using their registered names; +other encodings SHOULD use names starting with an "x-" prefix. +XML processors SHOULD match character encoding names in a case-insensitive +way and SHOULD either interpret an IANA-registered name as the encoding registered +at IANA for that name or treat it as unknown (processors are, of course, not +required to support all IANA-registered encodings).

In the absence of information provided by an external transport protocol +(e.g. HTTP or MIME), it is a fatal error for +an entity including an encoding declaration to be presented to the XML processor +in an encoding other than that named in the declaration, or for an entity which +begins with neither a Byte Order Mark +nor an encoding declaration to use an encoding other than UTF-8. Note that +since ASCII is a subset of UTF-8, ordinary ASCII entities do not strictly +need an encoding declaration.

It is a fatal error for a TextDecl to occur other +than at the beginning of an external entity.

It is a fatal error when an XML processor +encounters an entity with an encoding that it is unable to process. It +is a fatal error if an XML entity is determined (via default, encoding declaration, +or higher-level protocol) to be in a certain encoding but contains byte +sequences that are not legal in that encoding. Specifically, it is a +fatal error if an entity encoded in UTF-8 contains any ill-formed code unit sequences, +as defined in section 3.9 of Unicode [Unicode]. Unless an encoding +is determined by a higher-level protocol, it is also a fatal error if an XML entity +contains no encoding declaration and its content is not legal UTF-8 or UTF-16.

Examples of text declarations containing encoding declarations:

<?xml encoding='UTF-8'?>
+<?xml encoding='EUC-JP'?>
+

4.4 XML Processor Treatment of Entities and References

The table below summarizes the contexts in which character references, +entity references, and invocations of unparsed entities might appear and the +REQUIRED behavior of an XML processor +in each case. The labels in the leftmost column describe the recognition context:

Reference in Content

as a reference anywhere after the start-tag +and before the end-tag of an element; corresponds +to the nonterminal content.

Reference in Attribute Value

as a reference within either the value of an attribute in a start-tag, +or a default value in an attribute declaration; +corresponds to the nonterminal AttValue.

Occurs as Attribute Value

as a Name, not a reference, appearing either as +the value of an attribute which has been declared as type ENTITY, +or as one of the space-separated tokens in the value of an attribute which +has been declared as type ENTITIES.

Reference in Entity Value

as a reference within a parameter or internal entity's literal +entity value in the entity's declaration; corresponds to the nonterminal EntityValue.

Reference in DTD

as a reference within either the internal or external subsets of the DTD, but outside of an EntityValue, AttValue, PI, Comment, SystemLiteral, PubidLiteral, +or the contents of an ignored conditional section (see 3.4 Conditional Sections).

.

+

Entity +TypeCharacter
ParameterInternal GeneralExternal Parsed +GeneralUnparsed
Reference +in Content + Not recognized + + Included + + Included +if validating + + Forbidden + + Included +
Reference in Attribute Value + Not recognized + + Included +in literal + + Forbidden + + Forbidden + + Included +
Occurs as Attribute +Value + Not recognized + + Forbidden + + Forbidden + + Notify + + Not recognized +
Reference in EntityValue + Included in literal + + Bypassed + + Bypassed + + Error + + Included +
Reference in DTD + Included as PE + + Forbidden + + Forbidden + + Forbidden + + Forbidden +
+

4.4.1 Not Recognized

Outside the DTD, the % character has no special significance; +thus, what would be parameter entity references in the DTD are not recognized +as markup in content. Similarly, the names of unparsed +entities are not recognized except when they appear in the value of an appropriately +declared attribute.

+

4.4.2 Included

+ [Definition: An entity is included +when its replacement text is retrieved +and processed, in place of the reference itself, as though it were part of +the document at the location the reference was recognized.] The replacement +text may contain both character data +and (except for parameter entities) markup, +which MUST be recognized in the usual way. (The string " + AT&amp;T; + " +expands to " + AT&T; + " and the remaining ampersand +is not recognized as an entity-reference delimiter.) A character reference +is included when the indicated character is processed in place +of the reference itself.

+

4.4.3 Included If Validating

When an XML processor recognizes a reference to a parsed entity, in order +to validate the document, the processor +MUST + include its replacement text. If +the entity is external, and the processor is not attempting to validate the +XML document, the processor MAY, but need +not, include the entity's replacement text. If a non-validating processor +does not include the replacement text, it MUST inform the application that +it recognized, but did not read, the entity.

This rule is based on the recognition that the automatic inclusion provided +by the SGML and XML entity mechanism, primarily designed to support modularity +in authoring, is not necessarily appropriate for other applications, in particular +document browsing. Browsers, for example, when encountering an external parsed +entity reference, might choose to provide a visual indication of the entity's +presence and retrieve it for display only on demand.

+

4.4.4 Forbidden

The following are forbidden, and constitute fatal +errors:

  • the appearance of a reference to an unparsed +entity, except in the +EntityValue in an entity declaration.

  • the appearance of any character or general-entity reference in the +DTD except within an EntityValue or AttValue.

  • a reference to an external entity in an attribute value.

+

4.4.5 Included in Literal

When an entity reference appears in +an attribute value, or a parameter entity reference appears in a literal entity +value, its replacement text + MUST be processed +in place of the reference itself as though it were part of the document at +the location the reference was recognized, except that a single or double +quote character in the replacement text MUST always be treated as a normal data +character and MUST NOT terminate the literal. For example, this is well-formed:

<!ENTITY % YN '"Yes"' >
+<!ENTITY WhatHeSaid "He said %YN;" >

while this is not:

<!ENTITY EndAttr "27'" >
+<element attribute='a-&EndAttr;>
+

4.4.6 Notify

When the name of an unparsed entity +appears as a token in the value of an attribute of declared type ENTITY +or ENTITIES, a validating processor MUST inform the application of +the system and public +(if any) identifiers for both the entity and its associated notation.

+

4.4.7 Bypassed

When a general entity reference appears in the EntityValue +in an entity declaration, it MUST be bypassed and left as is.

+

4.4.8 Included as PE

Just as with external parsed entities, parameter entities need only be included if validating. When a parameter-entity +reference is recognized in the DTD and included, its replacement +text + MUST be enlarged by the attachment of one leading and one following +space (#x20) character; the intent is to constrain the replacement text of +parameter entities to contain an integral number of grammatical tokens in +the DTD. This +behavior MUST NOT apply to parameter entity references within entity values; +these are described in 4.4.5 Included in Literal.

+

4.4.9 Error

It is an error for a reference to + an unparsed entity to appear in the EntityValue in an + entity declaration.

+

4.5 Construction of Entity Replacement Text

In discussing the treatment of entities, it is useful to distinguish +two forms of the entity's value. +[Definition: For an +internal entity, the literal +entity value is the quoted string actually present in the entity declaration, +corresponding to the non-terminal EntityValue.] + [Definition: For an external entity, the literal +entity value is the exact text contained in the entity.] + [Definition: For an +internal entity, the replacement text +is the content of the entity, after replacement of character references and +parameter-entity references.] + [Definition: For +an external entity, the replacement text is the content of the entity, +after stripping the text declaration (leaving any surrounding whitespace) if there +is one but without any replacement of character references or parameter-entity +references.] +

The literal entity value as given in an internal entity declaration (EntityValue) may contain character, parameter-entity, +and general-entity references. Such references MUST be contained entirely +within the literal entity value. The actual replacement text that is included (or included in literal) as described above +MUST contain the replacement +text of any parameter entities referred to, and MUST contain the character +referred to, in place of any character references in the literal entity value; +however, general-entity references MUST be left as-is, unexpanded. For example, +given the following declarations:

<!ENTITY % pub    "&#xc9;ditions Gallimard" >
+<!ENTITY   rights "All rights reserved" >
+<!ENTITY   book   "La Peste: Albert Camus,
+&#xA9; 1947 %pub;. &rights;" >

then the replacement text for the entity " + book + " +is:

La Peste: Albert Camus,
+© 1947 Éditions Gallimard. &rights;

The general-entity reference " + &rights; + " would +be expanded should the reference " + &book; + " appear +in the document's content or an attribute value.

These simple rules may have complex interactions; for a detailed discussion +of a difficult example, see D Expansion of Entity and Character References.

+

4.6 Predefined Entities

+ [Definition: Entity and character references may +both be used to escape the left angle bracket, ampersand, and +other delimiters. A set of general entities (amp, +lt, +gt, +apos, +quot) is specified for +this purpose. Numeric character references may also be used; they are expanded +immediately when recognized and MUST be treated as character data, so the +numeric character references " + &#60; + " and " + &#38; + " may be used to escape < and & when they occur +in character data.] +

All XML processors MUST recognize these entities whether they are declared +or not. For interoperability, valid XML +documents SHOULD declare these entities, like any others, before using them. If +the entities lt or amp are declared, they MUST be +declared as internal entities whose replacement text is a character reference +to the respective +character (less-than sign or ampersand) being escaped; the double +escaping is REQUIRED for these entities so that references to them produce +a well-formed result. If the entities gt, apos, +or quot are declared, they MUST be declared as internal entities +whose replacement text is the single character being escaped (or a character +reference to that character; the double escaping here is OPTIONAL but harmless). +For example:

<!ENTITY lt     "&#38;#60;">
+<!ENTITY gt     "&#62;">
+<!ENTITY amp    "&#38;#38;">
+<!ENTITY apos   "&#39;">
+<!ENTITY quot   "&#34;">
+

4.7 Notation Declarations

+ [Definition: + Notations identify +by name the format of unparsed entities, +the format of elements which bear a notation attribute, or the application +to which a processing instruction is addressed.] +

+ [Definition: + Notation declarations +provide a name for the notation, for use in entity and attribute-list declarations +and in attribute specifications, and an external identifier for the notation +which may allow an XML processor or its client application to locate a helper +application capable of processing data in the given notation.] +

+
Notation Declarations
[82]   NotationDecl   ::=   '<!NOTATION' S + Name + S (ExternalID | PublicID) S? '>'[VC: Unique Notation Name]
[83]   PublicID   ::=   'PUBLIC' S + PubidLiteral +

Validity constraint: Unique Notation Name

A given Name + MUST NOT be declared in more than one notation declaration.

XML processors MUST provide applications with the name and external identifier(s) +of any notation declared and referred to in an attribute value, attribute +definition, or entity declaration. They MAY additionally resolve the external +identifier into the system identifier, file +name, or other information needed to allow the application to call a processor +for data in the notation described. (It is not an error, however, for XML +documents to declare and refer to notations for which notation-specific applications +are not available on the system where the XML processor or application is +running.)

+

4.8 Document Entity

+ [Definition: The document entity +serves as the root of the entity tree and a starting-point for an XML processor.] This specification does +not specify how the document entity is to be located by an XML processor; +unlike other entities, the document entity has no name and might well appear +on a processor input stream without any identification at all.

+

5 Conformance

+

5.1 Validating and Non-Validating Processors

Conforming XML processors fall into +two classes: validating and non-validating.

Validating and non-validating processors alike MUST report violations of +this specification's well-formedness constraints in the content of the document entity and any other parsed +entities that they read.

+ [Definition: + Validating +processors + MUST, +at user option, report violations of the constraints expressed by +the declarations in the DTD, and failures +to fulfill the validity constraints given in this specification.] +To accomplish this, validating XML processors MUST read and process the entire +DTD and all external parsed entities referenced in the document.

Non-validating processors are REQUIRED to check only the document +entity, including the entire internal DTD subset, for well-formedness. [Definition: While they are not required +to check the document for validity, they are REQUIRED to process +all the declarations they read in the internal DTD subset and in any parameter +entity that they read, up to the first reference to a parameter entity that +they do not read; that is to say, they MUST use the information +in those declarations to normalize +attribute values, include the replacement +text of internal entities, and supply default +attribute values.] Except when standalone="yes", they +MUST NOT + process + entity +declarations or attribute-list declarations +encountered after a reference to a parameter entity that is not read, since +the entity may have contained overriding declarations; when standalone="yes", processors MUST +process these declarations.

Note that when processing invalid documents with a non-validating +processor the application may not be presented with consistent +information. For example, several requirements for uniqueness +within the document may not be met, including more than one element +with the same id, duplicate declarations of elements or notations +with the same name, etc. In these cases the behavior of the parser +with respect to reporting such information to the application is +undefined.

+

5.2 Using XML Processors

The behavior of a validating XML processor is highly predictable; it must +read every piece of a document and report all well-formedness and validity +violations. Less is required of a non-validating processor; it need not read +any part of the document other than the document entity. This has two effects +that may be important to users of XML processors:

For maximum reliability in interoperating between different XML processors, +applications which use non-validating processors SHOULD NOT rely on any behaviors +not required of such processors. Applications which require DTD facilities not related to validation (such +as the declaration of default attributes and internal entities that are or may be specified in +external entities) SHOULD use validating XML processors.

+

6 Notation

The formal grammar of XML is given in this specification using a simple +Extended Backus-Naur Form (EBNF) notation. Each rule in the grammar defines +one symbol, in the form

symbol ::= expression

Symbols are written with an initial capital letter if they are the +start symbol of a regular language, otherwise with an initial lowercase letter. +Literal strings are quoted.

Within the expression on the right-hand side of a rule, the following expressions +are used to match strings of one or more characters:

+ #xN +

where N is a hexadecimal integer, the expression matches the character +whose number +(code point) in ISO/IEC 10646 is N. The number of leading zeros in the #xN +form is insignificant.

+ [a-zA-Z], [#xN-#xN] +

matches any Char with a value in the range(s) indicated (inclusive).

+ [abc], [#xN#xN#xN] +

matches any Char with a value among the characters +enumerated. Enumerations and ranges can be mixed in one set of brackets.

+ [^a-z], [^#xN-#xN] +

matches any Char with a value outside the range +indicated.

+ [^abc], [^#xN#xN#xN] +

matches any Char with a value not among the characters given. Enumerations +and ranges of forbidden values can be mixed in one set of brackets.

+ "string" +

matches a literal string matching that +given inside the double quotes.

+ 'string' +

matches a literal string matching that +given inside the single quotes.

These symbols may be combined to match more complex patterns as follows, +where A and B represent simple expressions:

(expression)

+ expression is treated as a unit and may be combined as described +in this list.

+ A? +

matches A or nothing; optional A.

+ A B +

matches A followed by B. This +operator has higher precedence than alternation; thus A B | C D +is identical to (A B) | (C D).

+ A | B +

matches A or B.

+ A - B +

matches any string that matches A but does not match B.

+ A+ +

matches one or more occurrences of A. Concatenation +has higher precedence than alternation; thus A+ | B+ is identical +to (A+) | (B+).

+ A* +

matches zero or more occurrences of A. Concatenation +has higher precedence than alternation; thus A* | B* is identical +to (A*) | (B*).

Other notations used in the productions are:

+ /* ... */ +

comment.

+ [ wfc: ... ] +

well-formedness constraint; this identifies by name a constraint on well-formed documents associated with a production.

+ [ vc: ... ] +

validity constraint; this identifies by name a constraint on valid +documents associated with a production.

+

+

A References

+

A.1 Normative References

IANA-CHARSETS
(Internet +Assigned Numbers Authority) Official Names for Character Sets, +ed. Keld Simonsen et al. (See http://www.iana.org/assignments/character-sets.)
IETF RFC 2119
IETF +(Internet Engineering Task Force). RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. +Scott Bradner, 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
IETF BCP 47
IETF + (Internet Engineering Task Force). BCP 47, consisting of RFC 4646: Tags for Identifying Languages, and RFC 4647: Matching of Language Tags, + A. Phillips, M. Davis. 2006.
IETF RFC 3986
IETF (Internet Engineering Task Force). RFC 3986: Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee, R. Fielding, L. Masinter. 2005. (See http://www.ietf.org/rfc/rfc3986.txt.)
ISO/IEC 10646
ISO (International +Organization for Standardization). ISO/IEC 10646-1:2000. Information +technology — Universal Multiple-Octet Coded Character Set (UCS) — +Part 1: Architecture and Basic Multilingual Plane and ISO/IEC 10646-2:2001. +Information technology — Universal Multiple-Octet Coded Character Set (UCS) — Part 2: +Supplementary Planes, as, from time to time, amended, replaced by a new edition or +expanded by the addition of new parts. [Geneva]: International Organization for Standardization. +(See http://www.iso.org/iso/home.htm for the latest version.)
ISO/IEC 10646:2000
ISO (International +Organization for Standardization). ISO/IEC 10646-1:2000. Information +technology — Universal Multiple-Octet Coded Character Set (UCS) — +Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International +Organization for Standardization, 2000.
Unicode
The Unicode Consortium. The Unicode +Standard, Version 5.0.0, defined by: The Unicode Standard, Version 5.0 (Boston, MA, +Addison-Wesley, 2007. ISBN 0-321-48091-0).
UnicodeNormal
The Unicode +Consortium. Unicode normalization forms. Mark Davis and +Martin Durst. 2008. (See http://unicode.org/reports/tr15/.)
+

A.2 Other References

Aho/Ullman
Aho, Alfred V., Ravi Sethi, and Jeffrey D. +Ullman. Compilers: Principles, Techniques, and Tools. +Reading: Addison-Wesley, 1986, rpt. corr. 1988.
Brüggemann-Klein
Brüggemann-Klein, +Anne. Formal Models in Document Processing. Habilitationsschrift. Faculty +of Mathematics at the University of Freiburg, 1993. (See ftp://ftp.informatik.uni-freiburg.de/documents/papers/brueggem/habil.ps.)
Brüggemann-Klein and Wood
Brüggemann-Klein, +Anne, and Derick Wood. Deterministic Regular Languages. +Universität Freiburg, Institut für Informatik, Bericht 38, Oktober 1991. Extended +abstract in A. Finkel, M. Jantzen, Hrsg., STACS 1992, S. 173-184. Springer-Verlag, +Berlin 1992. Lecture Notes in Computer Science 577. Full version titled One-Unambiguous +Regular Languages in Information and Computation 140 (2): 229-253, +February 1998.
Clark
James Clark. +Comparison of SGML and XML. (See http://www.w3.org/TR/NOTE-sgml-xml-971215.)
IANA-LANGCODES
(Internet +Assigned Numbers Authority) Registry of Language Tags (See http://www.iana.org/assignments/language-subtag-registry.)
IETF RFC 2141
IETF +(Internet Engineering Task Force). RFC 2141: URN Syntax, ed. +R. Moats. 1997. (See http://www.ietf.org/rfc/rfc2141.txt.)
IETF RFC 3023
IETF +(Internet Engineering Task Force). RFC 3023: XML Media Types. +eds. M. Murata, S. St.Laurent, D. Kohn. 2001. (See http://www.ietf.org/rfc/rfc3023.txt.)
IETF RFC 2781
IETF +(Internet Engineering Task Force). RFC 2781: UTF-16, an encoding +of ISO 10646, ed. P. Hoffman, F. Yergeau. 2000. (See http://www.ietf.org/rfc/rfc2781.txt.)
ISO 639
(International Organization for Standardization). +ISO 639:1988 (E). +Code for the representation of names of languages. [Geneva]: International +Organization for Standardization, 1988.
ISO 3166
(International Organization for Standardization). +ISO 3166-1:1997 +(E). Codes for the representation of names of countries and their subdivisions — +Part 1: Country codes [Geneva]: International Organization for +Standardization, 1997.
ISO 8879
ISO (International Organization for Standardization). ISO +8879:1986(E). Information processing — Text and Office Systems — +Standard Generalized Markup Language (SGML). First edition — +1986-10-15. [Geneva]: International Organization for Standardization, 1986.
ISO/IEC 10744
ISO (International Organization for +Standardization). ISO/IEC 10744-1992 (E). Information technology — +Hypermedia/Time-based Structuring Language (HyTime). [Geneva]: +International Organization for Standardization, 1992. Extended Facilities +Annexe. [Geneva]: International Organization for Standardization, 1996.
WEBSGML
ISO +(International Organization for Standardization). ISO 8879:1986 +TC2. Information technology — Document Description and Processing Languages. +[Geneva]: International Organization for Standardization, 1998. (See http://www.sgmlsource.com/8879/n0029.htm.)
XML Names
Tim Bray, +Dave Hollander, and Andrew Layman, editors. Namespaces in XML. +Textuality, Hewlett-Packard, and Microsoft. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/xml-names/.)
+

B Character Classes

Because of changes to productions + [4] and [5], the productions in + this Appendix are now orphaned and not used anymore in determining + name characters. This Appendix may be removed in a future edition of + this specification; other specifications that wish to refer to the productions herein should + do so by means of a reference to the relevant production(s) in the + Fourth Edition of this specification.

Following the characteristics defined in the Unicode standard, characters +are classed as base characters (among others, these contain the alphabetic +characters of the Latin alphabet), ideographic characters, and combining characters (among +others, this class contains most diacritics). Digits and extenders are also +distinguished.

+
Characters
[84]   Letter   ::=    + BaseChar | Ideographic +
[85]   BaseChar   ::=   [#x0041-#x005A] | [#x0061-#x007A] | [#x00C0-#x00D6] +| [#x00D8-#x00F6] | [#x00F8-#x00FF] | [#x0100-#x0131] | [#x0134-#x013E] +| [#x0141-#x0148] | [#x014A-#x017E] | [#x0180-#x01C3] | [#x01CD-#x01F0] +| [#x01F4-#x01F5] | [#x01FA-#x0217] | [#x0250-#x02A8] | [#x02BB-#x02C1] +| #x0386 | [#x0388-#x038A] | #x038C | [#x038E-#x03A1] +| [#x03A3-#x03CE] | [#x03D0-#x03D6] | #x03DA | #x03DC +| #x03DE | #x03E0 | [#x03E2-#x03F3] | [#x0401-#x040C] +| [#x040E-#x044F] | [#x0451-#x045C] | [#x045E-#x0481] | [#x0490-#x04C4] +| [#x04C7-#x04C8] | [#x04CB-#x04CC] | [#x04D0-#x04EB] | [#x04EE-#x04F5] +| [#x04F8-#x04F9] | [#x0531-#x0556] | #x0559 | [#x0561-#x0586] +| [#x05D0-#x05EA] | [#x05F0-#x05F2] | [#x0621-#x063A] | [#x0641-#x064A] +| [#x0671-#x06B7] | [#x06BA-#x06BE] | [#x06C0-#x06CE] | [#x06D0-#x06D3] +| #x06D5 | [#x06E5-#x06E6] | [#x0905-#x0939] | #x093D +| [#x0958-#x0961] | [#x0985-#x098C] | [#x098F-#x0990] | [#x0993-#x09A8] +| [#x09AA-#x09B0] | #x09B2 | [#x09B6-#x09B9] | [#x09DC-#x09DD] +| [#x09DF-#x09E1] | [#x09F0-#x09F1] | [#x0A05-#x0A0A] | [#x0A0F-#x0A10] +| [#x0A13-#x0A28] | [#x0A2A-#x0A30] | [#x0A32-#x0A33] | [#x0A35-#x0A36] +| [#x0A38-#x0A39] | [#x0A59-#x0A5C] | #x0A5E | [#x0A72-#x0A74] +| [#x0A85-#x0A8B] | #x0A8D | [#x0A8F-#x0A91] | [#x0A93-#x0AA8] +| [#x0AAA-#x0AB0] | [#x0AB2-#x0AB3] | [#x0AB5-#x0AB9] | #x0ABD +| #x0AE0 | [#x0B05-#x0B0C] | [#x0B0F-#x0B10] | [#x0B13-#x0B28] +| [#x0B2A-#x0B30] | [#x0B32-#x0B33] | [#x0B36-#x0B39] | #x0B3D +| [#x0B5C-#x0B5D] | [#x0B5F-#x0B61] | [#x0B85-#x0B8A] | [#x0B8E-#x0B90] +| [#x0B92-#x0B95] | [#x0B99-#x0B9A] | #x0B9C | [#x0B9E-#x0B9F] +| [#x0BA3-#x0BA4] | [#x0BA8-#x0BAA] | [#x0BAE-#x0BB5] | [#x0BB7-#x0BB9] +| [#x0C05-#x0C0C] | [#x0C0E-#x0C10] | [#x0C12-#x0C28] | [#x0C2A-#x0C33] +| [#x0C35-#x0C39] | [#x0C60-#x0C61] | [#x0C85-#x0C8C] | [#x0C8E-#x0C90] +| [#x0C92-#x0CA8] | [#x0CAA-#x0CB3] | [#x0CB5-#x0CB9] | #x0CDE +| [#x0CE0-#x0CE1] | [#x0D05-#x0D0C] | [#x0D0E-#x0D10] | [#x0D12-#x0D28] +| [#x0D2A-#x0D39] | [#x0D60-#x0D61] | [#x0E01-#x0E2E] | #x0E30 +| [#x0E32-#x0E33] | [#x0E40-#x0E45] | [#x0E81-#x0E82] | #x0E84 +| [#x0E87-#x0E88] | #x0E8A | #x0E8D | [#x0E94-#x0E97] +| [#x0E99-#x0E9F] | [#x0EA1-#x0EA3] | #x0EA5 | #x0EA7 +| [#x0EAA-#x0EAB] | [#x0EAD-#x0EAE] | #x0EB0 | [#x0EB2-#x0EB3] +| #x0EBD | [#x0EC0-#x0EC4] | [#x0F40-#x0F47] | [#x0F49-#x0F69] +| [#x10A0-#x10C5] | [#x10D0-#x10F6] | #x1100 | [#x1102-#x1103] +| [#x1105-#x1107] | #x1109 | [#x110B-#x110C] | [#x110E-#x1112] +| #x113C | #x113E | #x1140 | #x114C | #x114E | #x1150 +| [#x1154-#x1155] | #x1159 | [#x115F-#x1161] | #x1163 +| #x1165 | #x1167 | #x1169 | [#x116D-#x116E] | [#x1172-#x1173] +| #x1175 | #x119E | #x11A8 | #x11AB | [#x11AE-#x11AF] +| [#x11B7-#x11B8] | #x11BA | [#x11BC-#x11C2] | #x11EB +| #x11F0 | #x11F9 | [#x1E00-#x1E9B] | [#x1EA0-#x1EF9] +| [#x1F00-#x1F15] | [#x1F18-#x1F1D] | [#x1F20-#x1F45] | [#x1F48-#x1F4D] +| [#x1F50-#x1F57] | #x1F59 | #x1F5B | #x1F5D | [#x1F5F-#x1F7D] +| [#x1F80-#x1FB4] | [#x1FB6-#x1FBC] | #x1FBE | [#x1FC2-#x1FC4] +| [#x1FC6-#x1FCC] | [#x1FD0-#x1FD3] | [#x1FD6-#x1FDB] | [#x1FE0-#x1FEC] +| [#x1FF2-#x1FF4] | [#x1FF6-#x1FFC] | #x2126 | [#x212A-#x212B] +| #x212E | [#x2180-#x2182] | [#x3041-#x3094] | [#x30A1-#x30FA] +| [#x3105-#x312C] | [#xAC00-#xD7A3]
[86]   Ideographic   ::=   [#x4E00-#x9FA5] | #x3007 | [#x3021-#x3029]
[87]   CombiningChar   ::=   [#x0300-#x0345] | [#x0360-#x0361] | [#x0483-#x0486] +| [#x0591-#x05A1] | [#x05A3-#x05B9] | [#x05BB-#x05BD] | #x05BF +| [#x05C1-#x05C2] | #x05C4 | [#x064B-#x0652] | #x0670 +| [#x06D6-#x06DC] | [#x06DD-#x06DF] | [#x06E0-#x06E4] | [#x06E7-#x06E8] +| [#x06EA-#x06ED] | [#x0901-#x0903] | #x093C | [#x093E-#x094C] +| #x094D | [#x0951-#x0954] | [#x0962-#x0963] | [#x0981-#x0983] +| #x09BC | #x09BE | #x09BF | [#x09C0-#x09C4] | [#x09C7-#x09C8] +| [#x09CB-#x09CD] | #x09D7 | [#x09E2-#x09E3] | #x0A02 +| #x0A3C | #x0A3E | #x0A3F | [#x0A40-#x0A42] | [#x0A47-#x0A48] +| [#x0A4B-#x0A4D] | [#x0A70-#x0A71] | [#x0A81-#x0A83] | #x0ABC +| [#x0ABE-#x0AC5] | [#x0AC7-#x0AC9] | [#x0ACB-#x0ACD] | [#x0B01-#x0B03] +| #x0B3C | [#x0B3E-#x0B43] | [#x0B47-#x0B48] | [#x0B4B-#x0B4D] +| [#x0B56-#x0B57] | [#x0B82-#x0B83] | [#x0BBE-#x0BC2] | [#x0BC6-#x0BC8] +| [#x0BCA-#x0BCD] | #x0BD7 | [#x0C01-#x0C03] | [#x0C3E-#x0C44] +| [#x0C46-#x0C48] | [#x0C4A-#x0C4D] | [#x0C55-#x0C56] | [#x0C82-#x0C83] +| [#x0CBE-#x0CC4] | [#x0CC6-#x0CC8] | [#x0CCA-#x0CCD] | [#x0CD5-#x0CD6] +| [#x0D02-#x0D03] | [#x0D3E-#x0D43] | [#x0D46-#x0D48] | [#x0D4A-#x0D4D] +| #x0D57 | #x0E31 | [#x0E34-#x0E3A] | [#x0E47-#x0E4E] +| #x0EB1 | [#x0EB4-#x0EB9] | [#x0EBB-#x0EBC] | [#x0EC8-#x0ECD] +| [#x0F18-#x0F19] | #x0F35 | #x0F37 | #x0F39 | #x0F3E +| #x0F3F | [#x0F71-#x0F84] | [#x0F86-#x0F8B] | [#x0F90-#x0F95] +| #x0F97 | [#x0F99-#x0FAD] | [#x0FB1-#x0FB7] | #x0FB9 +| [#x20D0-#x20DC] | #x20E1 | [#x302A-#x302F] | #x3099 +| #x309A
[88]   Digit   ::=   [#x0030-#x0039] | [#x0660-#x0669] | [#x06F0-#x06F9] +| [#x0966-#x096F] | [#x09E6-#x09EF] | [#x0A66-#x0A6F] | [#x0AE6-#x0AEF] +| [#x0B66-#x0B6F] | [#x0BE7-#x0BEF] | [#x0C66-#x0C6F] | [#x0CE6-#x0CEF] +| [#x0D66-#x0D6F] | [#x0E50-#x0E59] | [#x0ED0-#x0ED9] | [#x0F20-#x0F29]
[89]   Extender   ::=   #x00B7 | #x02D0 | #x02D1 | #x0387 | #x0640 +| #x0E46 | #x0EC6 | #x3005 | [#x3031-#x3035] | [#x309D-#x309E] +| [#x30FC-#x30FE]

The character classes defined here can be derived from the Unicode 2.0 +character database as follows:

+

C XML and SGML (Non-Normative)

XML +is designed to be a subset of SGML, in that every XML document should also +be a conforming SGML document. For a detailed comparison of the additional +restrictions that XML places on documents beyond those of SGML, see [Clark].

+

D Expansion of Entity and Character References (Non-Normative)

This appendix contains some examples illustrating the sequence of entity- +and character-reference recognition and expansion, as specified in 4.4 XML Processor Treatment of Entities and References.

If the DTD contains the declaration

<!ENTITY example "<p>An ampersand (&#38;#38;) may be escaped
+numerically (&#38;#38;#38;) or with a general entity
+(&amp;amp;).</p>" >

then the XML processor will recognize the character references when it +parses the entity declaration, and resolve them before storing the following +string as the value of the entity " + example + ":

<p>An ampersand (&#38;) may be escaped
+numerically (&#38;#38;) or with a general entity
+(&amp;amp;).</p>

A reference in the document to " + &example; + " +will cause the text to be reparsed, at which time the start- and end-tags +of the p element will be recognized and the three references will +be recognized and expanded, resulting in a p element with the following +content (all data, no delimiters or markup):

An ampersand (&) may be escaped
+numerically (&#38;) or with a general entity
+(&amp;).

A more complex example will illustrate the rules and their effects fully. +In the following example, the line numbers are solely for reference.

1 <?xml version='1.0'?>
+2 <!DOCTYPE test [
+3 <!ELEMENT test (#PCDATA) >
+4 <!ENTITY % xx '&#37;zz;'>
+5 <!ENTITY % zz '&#60;!ENTITY tricky "error-prone" >' >
+6 %xx;
+7 ]>
+8 <test>This sample shows a &tricky; method.</test>

This produces the following:

  • in line 4, the reference to character 37 is expanded immediately, +and the parameter entity " + xx + " is stored in the symbol +table with the value " + %zz; + ". Since the replacement +text is not rescanned, the reference to parameter entity " + zz + " +is not recognized. (And it would be an error if it were, since " + zz + " +is not yet declared.)

  • in line 5, the character reference " + &#60; + " +is expanded immediately and the parameter entity " + zz + " +is stored with the replacement text " + <!ENTITY tricky "error-prone" +> + ", which is a well-formed entity declaration.

  • in line 6, the reference to " + xx + " is recognized, +and the replacement text of " + xx + " (namely " + %zz; + ") +is parsed. The reference to " + zz + " is recognized in +its turn, and its replacement text (" + <!ENTITY tricky "error-prone" +> + ") is parsed. The general entity " + tricky + " +has now been declared, with the replacement text " + error-prone + ".

  • in line 8, the reference to the general entity " + tricky + " +is recognized, and it is expanded, so the full content of the test +element is the self-describing (and ungrammatical) string This sample +shows a error-prone method. +

In the following example

<!DOCTYPE foo [ 
+<!ENTITY x "&lt;"> 
+]> 
+<foo attr="&x;"/>

the replacement text of x is the four characters "&lt;" because + references to general entities in entity values are bypassed. + The replacement text of lt is a character reference to + the less-than character, for example the five characters "&#60;" + (see 4.6 Predefined Entities). Since neither of these contains a less-than character + the result is well-formed.

If the definition of x had been

<!ENTITY x "&#60;">

then the document would not have been well-formed, because the + replacement text of x would be the single character "<" which + is not permitted in attribute values (see WFC: No < in Attribute Values).

+

E Deterministic Content Models (Non-Normative)

As +noted in 3.2.1 Element Content, it is required that content +models in element type declarations be deterministic. This requirement is for compatibility with SGML (which calls deterministic +content models "unambiguous"); XML processors built +using SGML systems may flag non-deterministic content models as errors.

For example, the content model ((b, c) | (b, d)) is non-deterministic, +because given an initial b the XML processor +cannot know which b in the model is being matched without looking +ahead to see which element follows the b. In this case, the two references +to b can be collapsed into a single reference, making the model read (b, +(c | d)). An initial b now clearly matches only a single name +in the content model. The processor doesn't need to look ahead to see what follows; either c or d +would be accepted.

More formally: a finite state automaton may be constructed from the content +model using the standard algorithms, e.g. algorithm 3.5 in section 3.9 of +Aho, Sethi, and Ullman [Aho/Ullman]. In many such algorithms, a follow +set is constructed for each position in the regular expression (i.e., each +leaf node in the syntax tree for the regular expression); if any position +has a follow set in which more than one following position is labeled with +the same element type name, then the content model is in error and may be +reported as an error.

Algorithms exist which allow many but not all non-deterministic content +models to be reduced automatically to equivalent deterministic models; see +Brüggemann-Klein 1991 [Brüggemann-Klein].

+

F Autodetection of Character Encodings (Non-Normative)

The XML encoding declaration functions as an internal label on each entity, +indicating which character encoding is in use. Before an XML processor can +read the internal label, however, it apparently has to know what character +encoding is in use—which is what the internal label is trying to indicate. +In the general case, this is a hopeless situation. It is not entirely hopeless +in XML, however, because XML limits the general case in two ways: each implementation +is assumed to support only a finite set of character encodings, and the XML +encoding declaration is restricted in position and content in order to make +it feasible to autodetect the character encoding in use in each entity in +normal cases. Also, in many cases other sources of information are available +in addition to the XML data stream itself. Two cases may be distinguished, +depending on whether the XML entity is presented to the processor without, +or with, any accompanying (external) information. We will consider + +these cases in turn.

+

F.1 Detection Without External Encoding Information

Because each XML entity not accompanied by external +encoding information and not in UTF-8 or UTF-16 encoding must +begin with an XML encoding declaration, in which the first characters must +be '<?xml', any conforming processor can detect, after two +to four octets of input, which of the following cases apply. In reading this +list, it may help to know that in UCS-4, '<' is " + #x0000003C + " +and '?' is " + #x0000003F + ", and the Byte Order Mark +required of UTF-16 data streams is " + #xFEFF + ". The notation +## is used to denote any byte value except that two consecutive +##s cannot be both 00.

With a Byte Order Mark:

+ 00 00 FE +FF + UCS-4, big-endian machine (1234 order)
+ FF +FE 00 00 + UCS-4, little-endian machine (4321 order)
+ 00 00 FF FE + UCS-4, unusual octet order (2143)
+ FE FF 00 00 + UCS-4, unusual octet order (3412)
+ FE FF ## ## + UTF-16, big-endian
+ FF FE ## ## + UTF-16, little-endian
+ EF BB BF + UTF-8

Without a Byte Order Mark:

+ 00 00 00 3C + UCS-4 or other encoding with a 32-bit code unit and ASCII +characters encoded as ASCII values, in respectively big-endian (1234), little-endian +(4321) and two unusual byte orders (2143 and 3412). The encoding declaration +must be read to determine which of UCS-4 or other supported 32-bit encodings +applies.
+ 3C 00 00 00 +
+ 00 00 3C 00 +
+ 00 3C 00 00 +
+ 00 3C 00 3F + UTF-16BE or big-endian ISO-10646-UCS-2 +or other encoding with a 16-bit code unit in big-endian order and ASCII characters +encoded as ASCII values (the encoding declaration must be read to determine +which)
+ 3C 00 3F 00 + UTF-16LE or little-endian +ISO-10646-UCS-2 or other encoding with a 16-bit code unit in little-endian +order and ASCII characters encoded as ASCII values (the encoding declaration +must be read to determine which)
+ 3C 3F 78 6D + UTF-8, ISO 646, ASCII, some part of ISO 8859, Shift-JIS, EUC, or any other +7-bit, 8-bit, or mixed-width encoding which ensures that the characters of +ASCII have their normal positions, width, and values; the actual encoding +declaration must be read to detect which of these applies, but since all of +these encodings use the same bit patterns for the relevant ASCII characters, +the encoding declaration itself may be read reliably
+ 4C +6F A7 94 + EBCDIC (in some flavor; the full encoding declaration +must be read to tell which code page is in use)
OtherUTF-8 without an encoding declaration, or else the data stream is mislabeled +(lacking a required encoding declaration), corrupt, fragmentary, or enclosed +in a wrapper of some kind

Note:

In cases above which do not require reading the encoding declaration to +determine the encoding, section 4.3.3 still requires that the encoding declaration, +if present, be read and that the encoding name be checked to match the actual +encoding of the entity. Also, it is possible that new character encodings +will be invented that will make it necessary to use the encoding declaration +to determine the encoding, in cases where this is not required at present.

This level of autodetection is enough to read the XML encoding declaration +and parse the character-encoding identifier, which is still necessary to distinguish +the individual members of each family of encodings (e.g. to tell UTF-8 from +8859, and the parts of 8859 from each other, or to distinguish the specific +EBCDIC code page in use, and so on).

Because the contents of the encoding declaration are restricted to characters +from the ASCII repertoire (however encoded), +a processor can reliably read the entire encoding declaration as soon as it +has detected which family of encodings is in use. Since in practice, all widely +used character encodings fall into one of the categories above, the XML encoding +declaration allows reasonably reliable in-band labeling of character encodings, +even when external sources of information at the operating-system or transport-protocol +level are unreliable. Character encodings such as UTF-7 +that make overloaded usage of ASCII-valued bytes may fail to be reliably detected.

Once the processor has detected the character encoding in use, it can act +appropriately, whether by invoking a separate input routine for each case, +or by calling the proper conversion function on each character of input.

Like any self-labeling system, the XML encoding declaration will not work +if any software changes the entity's character set or encoding without updating +the encoding declaration. Implementors of character-encoding routines should +be careful to ensure the accuracy of the internal and external information +used to label the entity.

+

F.2 Priorities in the Presence of External Encoding Information

The second possible case occurs when the XML entity is accompanied by encoding +information, as in some file systems and some network protocols. When multiple +sources of information are available, their relative priority and the preferred +method of handling conflict should be specified as part of the higher-level +protocol used to deliver XML. In particular, please refer +to [IETF RFC 3023] or its successor, which defines the text/xml +and application/xml MIME types and provides some useful guidance. +In the interests of interoperability, however, the following rule is recommended.

  • If an XML entity is in a file, the Byte-Order Mark and encoding declaration are used +(if present) to determine the character encoding.

+

G W3C XML Working Group (Non-Normative)

This specification was prepared and approved for publication by the W3C +XML Working Group (WG). WG approval of this specification does not necessarily +imply that all WG members voted for its approval. The current and former +participants of the XML WG are:

+

H W3C XML Core Working Group (Non-Normative)

The fifth edition of this specification was prepared by the W3C XML Core +Working Group (WG). The participants in the WG at the time of publication of this +edition were:

+

I Production Notes (Non-Normative)

This edition was encoded in a +slightly modified version of the +XMLspec DTD, v2.10. +The XHTML versions were produced with a combination of the +xmlspec.xsl, +diffspec.xsl, +and REC-xml.xsl +XSLT stylesheets.

+

J Suggestions for XML Names (Non-Normative)

The following suggestions define what is believed to be best + practice in the construction of XML names used as element names, + attribute names, processing instruction targets, entity names, + notation names, and the values of attributes of type ID, and are + intended as guidance for document authors and schema designers. + All references to Unicode are understood with respect to + a particular version of the Unicode Standard greater than or equal + to 5.0; which version should be used is left to the discretion of + the document author or schema designer.

The first two suggestions are directly derived from the rules + given for identifiers in Standard Annex #31 (UAX #31) of the Unicode Standard, version 5.0 [Unicode], and + exclude all control characters, enclosing nonspacing marks, + non-decimal numbers, private-use characters, punctuation characters + (with the noted exceptions), symbol characters, unassigned + codepoints, and white space characters. The other suggestions + are mostly derived from Appendix B in previous editions of this specification.

  1. The first character of any name should have a Unicode property + of ID_Start, or else be '_' #x5F.

  2. Characters other than the first should have a Unicode property + of ID_Continue, or be one of the characters listed in the table + entitled "Characters for Natural Language Identifiers" in UAX + #31, with the exception of "'" #x27 and "’" #x2019.

  3. Characters in names should be expressed using +Normalization Form C as defined in [UnicodeNormal].

  4. Ideographic characters which have a canonical decomposition + (including those in the ranges [#xF900-#xFAFF] and + [#x2F800-#x2FFFD], with 12 exceptions) should not be used in names. +

  5. Characters which have a compatibility decomposition (those with + a "compatibility formatting tag" in field 5 of the Unicode + Character Database -- marked by field 5 beginning with a "<") + should not be used in names. This suggestion does not apply + to characters which + despite their compatibility decompositions are in regular use in + their scripts, for +example #x0E33 THAI CHARACTER SARA AM or #x0EB3 LAO CHARACTER AM.

  6. Combining characters meant for use with symbols only (including + those in the ranges [#x20D0-#x20EF] and [#x1D165-#x1D1AD]) should + not be used in names.

  7. The interlinear annotation characters ([#xFFF9-#xFFFB]) should + not be used in names.

  8. Variation selector characters should not be used in names.

  9. Names which are nonsensical, unpronounceable, hard to read, or + easily confusable with other names should not be employed.

diff --git a/pyproject.toml b/pyproject.toml index 2c07666..306b16a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,6 +72,7 @@ include = [ "src/diffable_rdf", "tests", "docs/api.md", + "docs/standards", "CHANGELOG.md", "README.md", "LICENSE", diff --git a/scripts/check_standards.py b/scripts/check_standards.py new file mode 100644 index 0000000..64a5f1e --- /dev/null +++ b/scripts/check_standards.py @@ -0,0 +1,231 @@ +#!/usr/bin/env python3 +"""Verify pinned standards identities, notices, digests and clause anchors offline.""" + +from __future__ import annotations + +import argparse +from datetime import date +import hashlib +from html.parser import HTMLParser +import json +from pathlib import Path, PurePosixPath +import re +from typing import Any, Sequence +from urllib.parse import urlsplit + + +_MANIFEST = Path(__file__).resolve().parents[1] / "docs" / "standards" / "manifest.json" +_REFERENCE_IDS = frozenset( + { + "RDF11-CONCEPTS", "RDFC10", "TURTLE11", "TRIG11", "NTRIPLES11", "NQUADS11", "RDFXML11", + "JSONLD11", "JSONLD11-API", "XML10", "XMLNS10", "RFC3986", "RFC3987", "RFC8259", + } +) +_ASSET_FIELDS = frozenset( + {"id", "title", "source_url", "resolved_url", "path", "media_type", "retrieved_at", "sha256", "notice"} +) +_REFERENCE_FIELDS = _ASSET_FIELDS | {"edition", "publication_date", "status", "license_ids", "anchors"} + + +class ReferenceValidationError(ValueError): + """A reference catalog or one of its pinned assets is inconsistent.""" + + +class _Document(HTMLParser): + """Collect textual identity and both forms of HTML fragment identifiers.""" + + def __init__(self) -> None: + super().__init__(convert_charrefs=True) + self.anchors: set[str] = set() + self.text: list[str] = [] + self._hidden = 0 + + def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + if tag in {"script", "style"}: + self._hidden += 1 + for key, value in attrs: + if value and (key == "id" or (tag == "a" and key == "name")): + self.anchors.add(value) + + def handle_endtag(self, tag: str) -> None: + if tag in {"script", "style"} and self._hidden: + self._hidden -= 1 + + def handle_data(self, data: str) -> None: + if not self._hidden: + self.text.append(data) + + +def html_anchors(text: str) -> set[str]: + """Return the fragment identifiers present in an original HTML document.""" + document = _Document() + document.feed(text) + return document.anchors + + +def _require(condition: bool, message: str) -> None: + if not condition: + raise ReferenceValidationError(message) + + +def _strings(value: Any, label: str) -> list[str]: + _require(isinstance(value, list), f"{label} must be a list") + _require(all(isinstance(item, str) and item.strip() for item in value), f"{label} must contain nonempty strings") + _require(len(value) == len(set(value)), f"{label} contains duplicates") + return value + + +def _date(value: str, label: str, *, month_allowed: bool = False) -> None: + pattern = r"\d{4}-\d{2}(?:-\d{2})?" if month_allowed else r"\d{4}-\d{2}-\d{2}" + _require(re.fullmatch(pattern, value) is not None, f"{label} must be an ISO date") + try: + date.fromisoformat(value + "-01" if len(value) == 7 else value) + except ValueError as error: + raise ReferenceValidationError(f"{label} is not a valid date") from error + + +def _has_control_characters(value: str) -> bool: + return any(ord(character) < 32 or 127 <= ord(character) <= 159 for character in value) + + +def _https_url(value: str, label: str) -> None: + message = f"{label} must be an HTTPS URL with a hostname and valid port" + _require(not _has_control_characters(value) and not any(character.isspace() for character in value), message) + try: + url = urlsplit(value) + hostname = url.hostname + port = url.port + except ValueError as error: + raise ReferenceValidationError(message) from error + _require(url.scheme == "https" and bool(hostname) and not url.fragment, message) + _require(port is None or 0 <= port <= 65535, message) + + +def _contained_path(root: Path, value: str) -> Path: + path = PurePosixPath(value) + _require( + not path.is_absolute() and not _has_control_characters(value) + and not any(character in value for character in '\\:<>"|?*') + and all(part not in {"", ".", ".."} for part in value.split("/")) + and path.parts[0] == "references", + f"unsafe asset path: {value!r}", + ) + try: + resolved = (root / path).resolve() + reference_root = root.resolve() / "references" + except (OSError, RuntimeError, ValueError) as error: + raise ReferenceValidationError(f"cannot resolve asset path: {value!r}") from error + _require(resolved.is_relative_to(reference_root), f"asset path escapes references: {value!r}") + return resolved + + +def _asset(root: Path, item: Any, *, reference: bool) -> tuple[str, set[str]]: + _require(isinstance(item, dict), "asset must be an object") + expected = _REFERENCE_FIELDS if reference else _ASSET_FIELDS + _require(set(item) == expected, f"asset fields differ from schema: {item.get('id', '')}") + for field in expected - {"license_ids", "anchors"}: + _require(isinstance(item[field], str) and bool(item[field].strip()), f"{field} must be a nonempty string") + for field in ("source_url", "resolved_url"): + _https_url(item[field], field) + _date(item["retrieved_at"], "retrieved_at") + _require(item["media_type"] in {"text/html", "text/plain"}, "unsupported media_type") + _require(re.fullmatch(r"[a-f0-9]{64}", item["sha256"]) is not None, "sha256 must be 64 lowercase hex digits") + path = _contained_path(root, item["path"]) + try: + is_file = path.is_file() + data = path.read_bytes() if is_file else None + except (OSError, ValueError) as error: + raise ReferenceValidationError(f"cannot read asset: {item['path']!r}") from error + _require(data is not None, f"missing asset: {item['path']}") + _require(hashlib.sha256(data).hexdigest() == item["sha256"], f"digest mismatch: {item['path']}") + try: + text = data.decode("utf-8") + except UnicodeDecodeError as error: + raise ReferenceValidationError(f"asset is not UTF-8: {item['path']}") from error + document = _Document() + if item["media_type"] == "text/html": + document.feed(text) + text = " ".join(document.text) + normalized = " ".join(text.split()) + _require(" ".join(item["title"].split()) in normalized, f"title absent from asset: {item['id']}") + if reference: + _date(item["publication_date"], "publication_date", month_allowed=True) + _require(item["status"] in normalized, f"status absent from asset: {item['id']}") + _require(item["edition"] in normalized, f"edition absent from asset: {item['id']}") + _require("Copyright" in normalized, f"copyright notice absent from asset: {item['id']}") + _require(bool(_strings(item["license_ids"], "license_ids")), "license_ids must not be empty") + _require(isinstance(item["anchors"], list), "anchors must be a list") + names: set[str] = set() + for anchor in item["anchors"]: + _require( + isinstance(anchor, dict) and set(anchor) == {"id", "section", "normative"}, "invalid anchor fields" + ) + _require(isinstance(anchor["id"], str) and bool(anchor["id"]), "anchor id must be a nonempty string") + _require(isinstance(anchor["section"], str) and bool(anchor["section"]), "anchor section must be nonempty") + _require(type(anchor["normative"]) is bool, "anchor normative must be a boolean") + _require(anchor["id"] not in names, f"duplicate anchor: {anchor['id']}") + names.add(anchor["id"]) + _require(anchor["id"] in document.anchors, f"missing HTML anchor: {item['id']}#{anchor['id']}") + return item["id"], document.anchors + + +def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]: + result: dict[str, Any] = {} + for key, value in pairs: + _require(key not in result, f"duplicate JSON key: {key}") + result[key] = value + return result + + +def check_catalog(manifest_path: Path = _MANIFEST) -> dict[str, Any]: + """Validate the complete pinned inventory and return its parsed catalog.""" + try: + catalog = json.loads(manifest_path.read_text(encoding="utf-8"), object_pairs_hook=_unique_object) + except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error: + raise ReferenceValidationError(f"cannot read catalog: {error}") from error + _require( + isinstance(catalog, dict) and set(catalog) == {"schema_version", "references", "licenses"}, + "invalid catalog fields", + ) + _require(type(catalog["schema_version"]) is int and catalog["schema_version"] == 1, "unsupported schema_version") + for group in ("references", "licenses"): + _require(isinstance(catalog[group], list) and bool(catalog[group]), f"{group} must be a nonempty list") + ids: set[str] = set() + paths: set[str] = set() + resolved_paths: set[Path] = set() + for group in ("references", "licenses"): + for item in catalog[group]: + identity, _ = _asset(manifest_path.parent, item, reference=group == "references") + _require(identity not in ids, f"duplicate asset ID: {identity}") + _require(item["path"] not in paths, f"duplicate asset path: {item['path']}") + resolved = _contained_path(manifest_path.parent, item["path"]) + _require(resolved not in resolved_paths, f"duplicate resolved asset path: {item['path']}") + ids.add(identity) + paths.add(item["path"]) + resolved_paths.add(resolved) + reference_ids = {item["id"] for item in catalog["references"]} + _require(reference_ids == _REFERENCE_IDS, f"reference inventory differs: {sorted(reference_ids ^ _REFERENCE_IDS)}") + license_ids = {item["id"] for item in catalog["licenses"]} + for reference in catalog["references"]: + _require(set(reference["license_ids"]) <= license_ids, f"unknown license ID: {reference['id']}") + return catalog + + +def main(arguments: Sequence[str] | None = None) -> int: + """Check a catalog without network access or asset modifications.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--manifest", type=Path, default=_MANIFEST) + args = parser.parse_args(arguments) + try: + catalog = check_catalog(args.manifest) + except ReferenceValidationError as error: + print(f"standards verification failed: {error}") + return 1 + print( + f"verified {len(catalog['references'])} standards and {len(catalog['licenses'])} license/notice assets offline" + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/diffable_rdf/__init__.py b/src/diffable_rdf/__init__.py index 185ddf1..9749dcf 100644 --- a/src/diffable_rdf/__init__.py +++ b/src/diffable_rdf/__init__.py @@ -8,7 +8,7 @@ deterministic_turtle(graph) Diff-stable, idiomatic Turtle. The usual entry point. canonicalize_rdf_graph(graph, output_format="turtle") - RDFC-1.0 canonical serialization in Turtle, N-Triples, N-Quads, + Deterministic serialization using RDFC-1.0 labels in Turtle, N-Triples, N-Quads, RDF/XML, TriG, N3 or JSON-LD. Any other format name is delegated to rdflib with no determinism guarantee. deterministic_json(obj, indent=3, preserve_list_order_keys=None) @@ -22,6 +22,8 @@ Those labels, applied to a new list of quads. Contracts, error cases and per-format behavior are documented in docs/api.md. +The standards profile in docs/standards/README.md distinguishes dependency +labeling from standardized canonical N-Quads bytes and project-specific output. """ from __future__ import annotations diff --git a/src/diffable_rdf/canonicalize.py b/src/diffable_rdf/canonicalize.py index d9a972a..4faf983 100644 --- a/src/diffable_rdf/canonicalize.py +++ b/src/diffable_rdf/canonicalize.py @@ -17,7 +17,7 @@ ``Literal("x", datatype=XSD.string)``. This is an equivalence, not a normalization: RDF 1.1 Concepts §3.3 compares lexical forms character by character, so every *other* typed lexical form is preserved exactly. - https://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal + https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/#section-Graph-Literal 2. **Non-standard RDF**: Graphs with relative IRIs or generalized RDF terms are rejected by pyoxigraph. This function uses a deterministic rdflib @@ -586,8 +586,9 @@ def _assert_round_trips(source: rdflib.Graph, serialized: str, output_format: st """Raise if ``serialized`` does not say the same thing as ``source``. A canonical form that does not round-trip is worse than none: it - silently rewrites the graph. This function compares RDFC-1.0 canonical - forms, which is an exact isomorphism test, and is skipped when the + silently rewrites the graph. This function compares sorted RDF term + strings after RDFC-1.0 labeling, not standardized canonical N-Quads bytes. + This graph-isomorphism comparison is skipped when the source graph is not representable in pyoxigraph (the degraded path, which deliberately passes relative IRIs through verbatim and so cannot be compared this way). @@ -684,6 +685,9 @@ def canonicalize_rdf_graph( The graph is transferred to pyoxigraph via N-Triples, canonicalized with RDFC-1.0, sorted, and serialized back to the requested format. + RDFC-1.0 supplies blank-node labels; syntax-specific rendering is not a + claim of standardized canonical N-Quads bytes or a standalone RDFC + processor interface. See docs/standards/README.md for the exact profile. Prefix bindings are optional presentation for formats that support them (Turtle, TriG, N3, RDF/XML). A binding is retained when its rendering verifies; otherwise complete IRIs preserve the graph terms. diff --git a/src/diffable_rdf/jsonld.py b/src/diffable_rdf/jsonld.py index 8ff61a0..529a0ea 100644 --- a/src/diffable_rdf/jsonld.py +++ b/src/diffable_rdf/jsonld.py @@ -10,12 +10,14 @@ # never be sorted. An ``@context`` array is processed in order, each entry # overriding the last -- the JSON-LD 1.1 API's Context Processing Algorithm # (§4.1) wraps a non-array local context in an array at step 4 and iterates it -# at step 5: https://www.w3.org/TR/json-ld11-api/#context-processing-algorithm -# ``@list`` is *the* ordered container (JSON-LD 1.1 §4.3.1). +# at step 5: https://www.w3.org/TR/2020/REC-json-ld11-api-20200716/#context-processing-algorithm +# ``@list`` is the ordered container (normative JSON-LD 1.1 §9.7): +# https://www.w3.org/TR/2020/REC-json-ld11-20200716/#lists-and-sets # # ``@graph`` and ``@set`` are deliberately absent. JSON-LD arrays are unordered # unless a container says otherwise, and ``@set`` expresses an unordered set of -# data (§1.7; §4.3.2), so their arrays are sorted deterministically. +# data (§9.7), so their arrays are sorted deterministically. The explanation +# in §4.3 Value Ordering is informative, not the normative definition. _ORDERED_JSONLD_KEYWORDS: frozenset[str] = frozenset({"@context", "@list"}) # What ``preserve_list_order_keys`` defaults to. This is a superset of the @@ -338,7 +340,7 @@ def _deep_sort( # An array nested directly inside an ordered array is ordered # too: it expands to a nested list, not to a fresh unordered # value, so its order reaches the RDF as list structure just the - # same (``@list`` is *the* ordered container, JSON-LD 1.1 §4.3.1). + # same (``@list`` is the ordered container, JSON-LD 1.1 §9.7). # Carry the protection into array items only -- a dict starts a # fresh node object, which is the documented point where sorting # resumes. diff --git a/src/diffable_rdf/turtle.py b/src/diffable_rdf/turtle.py index 37914c8..f85a65d 100644 --- a/src/diffable_rdf/turtle.py +++ b/src/diffable_rdf/turtle.py @@ -147,14 +147,14 @@ def _canonical_dataset_form(dataset: pyoxigraph.Dataset) -> str: def _rdfc_canonical_form(graph: Graph) -> str | None: - """Return the RDFC-1.0 canonical N-Triples of ``graph``, as sorted lines. + """Return a sorted RDF term comparison key after RDFC-1.0 labeling. - RDFC-1.0 is a canonical form: two graphs are isomorphic exactly when - their canonical serializations are identical. Comparing these strings - is therefore an exact isomorphism test, and — unlike - ``rdflib.compare.isomorphic``, which canonicalizes in Python — it runs - in pyoxigraph's Rust implementation, which the pipeline already invokes - in phase 1. + For the representable RDF graph terms, canonical blank-node labels and + sorted term strings provide an isomorphism comparison. These internal + strings are not the standardized canonical N-Quads byte representation. + Labeling runs in pyoxigraph's Rust implementation, which the pipeline + already invokes in phase 1, rather than the Python canonicalization + used by ``rdflib.compare.isomorphic``. Returns ``None`` when the graph cannot be represented in pyoxigraph at all (non-standard RDF such as literal predicates). Callers treat that @@ -170,7 +170,7 @@ def _rdfc_canonical_form(graph: Graph) -> str | None: def _rdfc_canonical_text(data: str, rdf_format: pyoxigraph.RdfFormat) -> str: - """Return the exact RDFC-1.0 form of serialized RDF text.""" + """Return the internal labeled-term comparison key of serialized RDF text.""" dataset = pyoxigraph.Dataset(pyoxigraph.parse(data, format=rdf_format)) return _canonical_dataset_form(dataset) @@ -235,12 +235,12 @@ def deterministic_turtle(graph: Graph) -> str: ---------- .. [1] W3C (2024). "RDF Dataset Canonicalization." W3C Recommendation, 21 May 2024. Defines the RDFC-1.0 algorithm. - https://www.w3.org/TR/rdf-canon/ + https://www.w3.org/TR/2024/REC-rdf-canon-20240521/ .. [2] W3C (2014). "RDF 1.1 Turtle — Terse RDF Triple Language." - W3C Recommendation. https://www.w3.org/TR/turtle/ + W3C Recommendation. https://www.w3.org/TR/2014/REC-turtle-20140225/ .. [3] W3C (2014). "RDF 1.1 Concepts and Abstract Syntax", §3.3 Literals (literal term equality) and §3.6 Graph Comparison (isomorphism). - W3C Recommendation. https://www.w3.org/TR/rdf11-concepts/ + W3C Recommendation. https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/ """ _require_single_graph(graph) diff --git a/src/diffable_rdf/wl.py b/src/diffable_rdf/wl.py index ebe8f20..4c4e4c9 100644 --- a/src/diffable_rdf/wl.py +++ b/src/diffable_rdf/wl.py @@ -20,7 +20,7 @@ ---------- .. [1] W3C (2024). "RDF Dataset Canonicalization." W3C Recommendation, 21 May 2024. Defines the RDFC-1.0 algorithm. - https://www.w3.org/TR/rdf-canon/ + https://www.w3.org/TR/2024/REC-rdf-canon-20240521/ .. [2] Weisfeiler, B. & Leman, A. (1968). "The reduction of a graph to canonical form and the algebra which appears therein." """ diff --git a/tests/README.md b/tests/README.md index a56431a..99f212b 100644 --- a/tests/README.md +++ b/tests/README.md @@ -7,6 +7,7 @@ coupling independent concerns. | Group | Responsibility | Primary dimensions | | --- | --- | --- | | `harness/` | Test-target selection and child-process isolation | source and wheel provenance, interpreter configuration | +| `standards/` | Pinned reference integrity and standards evidence | document identities, source provenance, licenses, digests, clause anchors | | `contracts/` | Public API, accepted graph inputs, format names, and output framing | exports, annotations, input coercion, format guarantees | | `serialization/` | RDF document fidelity and serializer fallbacks | bases, namespaces, literals, XML, list identity, process determinism | | `properties/` | Seeded graph invariants | losslessness, idempotence, label independence, insertion-order independence | @@ -67,3 +68,14 @@ Run focused groups with standard pytest selection, for example: ```bash uv run --frozen pytest -q --package-under-test=source tests/serialization tests/wl ``` + +Verify the [standards reference collection](../docs/standards/README.md) without +network access or optional packages: + +```bash +python scripts/check_standards.py +``` + +The same reference checks run in `standards/` under both source and installed +targets. They establish the integrity of the reference evidence, not complete +implementation of every clause of each copied specification. diff --git a/tests/standards/test_references.py b/tests/standards/test_references.py new file mode 100644 index 0000000..e00db2c --- /dev/null +++ b/tests/standards/test_references.py @@ -0,0 +1,250 @@ +"""Reference catalog integrity across identity, content and path boundaries.""" + +from __future__ import annotations + +import copy +import hashlib +import importlib.util +import json +from pathlib import Path +import shutil +import subprocess +import sys + +import pytest + + +_ROOT = Path(__file__).resolve().parents[2] +_CATALOG = _ROOT / "docs" / "standards" / "manifest.json" + + +@pytest.fixture(scope="module") +def reference_checker(): + """Load the dependency-free reference checker by its explicit source path.""" + spec = importlib.util.spec_from_file_location("standards_checker", _ROOT / "scripts" / "check_standards.py") + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +@pytest.fixture +def catalog_copy(tmp_path: Path): + """Provide isolated catalog data and original asset bytes for boundary tests.""" + root = tmp_path / "standards" + shutil.copytree(_CATALOG.parent, root) + path = root / "manifest.json" + return path, json.loads(path.read_text(encoding="utf-8")) + + +def _save(path: Path, catalog: dict) -> None: + path.write_text(json.dumps(catalog), encoding="utf-8") + + +def test_original_catalog_verifies_without_modifying_assets(reference_checker) -> None: + """The committed inventory verifies with every byte and modification time intact.""" + files = [_CATALOG, *(_CATALOG.parent / "references").iterdir()] + before = {path: (hashlib.sha256(path.read_bytes()).hexdigest(), path.stat().st_mtime_ns) for path in files} + catalog = reference_checker.check_catalog(_CATALOG) + assert len(catalog["references"]) == 14 + assert len(catalog["licenses"]) == 7 + assert before == {path: (hashlib.sha256(path.read_bytes()).hexdigest(), path.stat().st_mtime_ns) for path in files} + + +@pytest.mark.parametrize( + ("mutation", "message"), + [ + (lambda c: c.update(schema_version=2), "schema_version"), + (lambda c: c.update(schema_version=True), "schema_version"), + (lambda c: c.update(unknown=True), "catalog fields"), + (lambda c: c.update(references={}), "references must be"), + (lambda c: c["references"].pop(), "reference inventory"), + (lambda c: c["references"][0].update(id="UNKNOWN"), "reference inventory"), + (lambda c: c["references"].append(copy.deepcopy(c["references"][0])), "duplicate asset ID"), + (lambda c: c["references"][0].update(sha256="0" * 64), "digest mismatch"), + (lambda c: c["references"][0].update(sha256="not-a-digest"), "sha256"), + (lambda c: c["references"][0].update(title="An unrelated title"), "title absent"), + (lambda c: c["references"][0].update(edition="31 December 2099"), "edition absent"), + (lambda c: c["references"][0].update(status="Draft Only"), "status absent"), + (lambda c: c["references"][0].pop("notice"), "asset fields"), + (lambda c: c["references"][0].update(notice=""), "nonempty string"), + (lambda c: c["references"][0].update(retrieved_at="2026-13-01"), "valid date"), + (lambda c: c["references"][0].update(publication_date="yesterday"), "ISO date"), + (lambda c: c["references"][0].update(source_url="file:///tmp/spec"), "HTTPS URL"), + (lambda c: c["references"][0].update(source_url="https://["), "HTTPS URL"), + (lambda c: c["references"][0].update(media_type="application/octet-stream"), "media_type"), + (lambda c: c["references"][0].update(license_ids=["UNKNOWN"]), "unknown license ID"), + (lambda c: c["references"][0].update(license_ids=[]), "must not be empty"), + (lambda c: c["references"][0]["anchors"][0].update(id="absent-clause"), "missing HTML anchor"), + (lambda c: c["references"][0]["anchors"][0].update(normative="yes"), "must be a boolean"), + (lambda c: c["licenses"][0].update(sha256="0" * 64), "digest mismatch"), + ], +) +def test_catalog_rejects_invalid_metadata(reference_checker, catalog_copy, mutation, message: str) -> None: + """Identity, schema, provenance and clause failures reject the whole catalog.""" + path, catalog = catalog_copy + mutation(catalog) + _save(path, catalog) + with pytest.raises(reference_checker.ReferenceValidationError, match=message): + reference_checker.check_catalog(path) + + +@pytest.mark.parametrize("field", ["source_url", "resolved_url"]) +@pytest.mark.parametrize( + "value", + [ + pytest.param("https://a b/", id="hostname-space"), + pytest.param("https://:80/a", id="missing-hostname"), + pytest.param("https://www.w3.org:bad/a", id="nonnumeric-port"), + pytest.param("https://www.w3.org:65536/a", id="port-out-of-range"), + pytest.param("https://www.w3.org:-1/a", id="negative-port"), + pytest.param("https://www.w3.org/null\x00", id="nul"), + pytest.param("https://www.w3.org/tab\t", id="tab"), + pytest.param("https://www.w3.org/line\n", id="line-feed"), + pytest.param("https://www.w3.org/line\r", id="carriage-return"), + pytest.param("https://www.w3.org/delete\x7f", id="delete-control"), + pytest.param("https://www.w3.org/control\x80", id="extended-control"), + pytest.param("https://www.w3.org/space\u00a0", id="unicode-space"), + ], +) +def test_catalog_rejects_malformed_urls(reference_checker, catalog_copy, field: str, value: str) -> None: + """Both provenance URLs require unambiguous HTTPS hostnames, ports and characters.""" + path, catalog = catalog_copy + catalog["references"][0][field] = value + _save(path, catalog) + with pytest.raises(reference_checker.ReferenceValidationError, match=f"{field} must be an HTTPS URL"): + reference_checker.check_catalog(path) + + +@pytest.mark.parametrize("asset_group", ["references", "licenses"]) +@pytest.mark.parametrize("damage", ["missing", "corrupt"]) +def test_catalog_rejects_damaged_assets(reference_checker, catalog_copy, asset_group: str, damage: str) -> None: + """Original standards and license files have the same existence and digest requirements.""" + path, catalog = catalog_copy + asset = path.parent / catalog[asset_group][0]["path"] + if damage == "missing": + asset.unlink() + else: + asset.write_bytes(asset.read_bytes() + b"\nchanged\n") + with pytest.raises(reference_checker.ReferenceValidationError, match="missing asset|digest mismatch"): + reference_checker.check_catalog(path) + + +@pytest.mark.parametrize("value", ["/tmp/spec.html", "../spec.html", "references/../spec.html", "references//spec.html", + "references/./spec.html", "C:/spec.html", "references\\spec.html", "other/spec.html"]) +def test_catalog_rejects_unsafe_paths(reference_checker, catalog_copy, value: str) -> None: + """Asset paths are portable, unambiguous and contained in the reference directory.""" + path, catalog = catalog_copy + catalog["references"][0]["path"] = value + _save(path, catalog) + with pytest.raises(reference_checker.ReferenceValidationError, match="unsafe asset path"): + reference_checker.check_catalog(path) + + +def test_catalog_rejects_duplicate_paths(reference_checker, catalog_copy) -> None: + """Different IDs cannot claim the same original asset.""" + path, catalog = catalog_copy + duplicate = copy.deepcopy(catalog["references"][0]) + duplicate["id"] = "ADDITIONAL" + catalog["references"].append(duplicate) + _save(path, catalog) + with pytest.raises(reference_checker.ReferenceValidationError, match="duplicate asset path"): + reference_checker.check_catalog(path) + + +def test_catalog_rejects_symlink_escape(reference_checker, catalog_copy, tmp_path: Path) -> None: + """A path inside the catalog must not resolve to a file outside it.""" + path, catalog = catalog_copy + asset = path.parent / catalog["references"][0]["path"] + outside = tmp_path / "external.html" + asset.rename(outside) + try: + asset.symlink_to(outside) + except OSError: + pytest.skip("symbolic links are not available to this test process") + with pytest.raises(reference_checker.ReferenceValidationError, match="escapes references"): + reference_checker.check_catalog(path) + + +def test_catalog_rejects_duplicate_json_keys(reference_checker, tmp_path: Path) -> None: + """Ambiguous JSON object keys fail before any asset lookup.""" + path = tmp_path / "manifest.json" + path.write_text('{"schema_version": 1, "schema_version": 1}', encoding="utf-8") + with pytest.raises(reference_checker.ReferenceValidationError, match="duplicate JSON key"): + reference_checker.check_catalog(path) + + +def test_html_anchor_extraction_supports_ids_and_named_anchors(reference_checker) -> None: + """Fragment lookup supports HTML identifiers and legacy named anchors.""" + assert reference_checker.html_anchors('
') == {"terms", "syntax"} + + +def test_checker_cli_runs_without_site_packages(tmp_path: Path) -> None: + """The standalone checker runs from a neutral directory using only the standard library.""" + result = subprocess.run( + [sys.executable, "-I", "-S", str(_ROOT / "scripts" / "check_standards.py")], + cwd=tmp_path, capture_output=True, text=True, check=False, + ) + assert result.returncode == 0, result.stdout + result.stderr + assert "verified 14 standards and 7 license/notice assets offline" in result.stdout + + +def test_checker_cli_reports_invalid_catalog(reference_checker, tmp_path: Path, capsys) -> None: + """Invalid input produces a failing exit status with a readable diagnostic.""" + assert reference_checker.main(["--manifest", str(tmp_path / "missing.json")]) == 1 + assert "standards verification failed" in capsys.readouterr().out + + +@pytest.mark.parametrize( + "value", + [ + pytest.param("references/null\x00.html", id="nul"), + pytest.param("references/line\n.html", id="line-feed"), + pytest.param("references/control\x80.html", id="extended-control"), + pytest.param('references/quote".html', id="quote"), + pytest.param("references/angle<.html", id="angle-bracket"), + pytest.param("references/pipe|.html", id="pipe"), + pytest.param("references/glob*.html", id="asterisk"), + pytest.param("references/query?.html", id="question-mark"), + ], +) +def test_checker_cli_rejects_invalid_path_characters(catalog_copy, value: str, tmp_path: Path) -> None: + """Invalid portable path characters produce a clean failing command-line result.""" + path, catalog = catalog_copy + catalog["references"][0]["path"] = value + _save(path, catalog) + result = subprocess.run( + [sys.executable, "-I", "-S", str(_ROOT / "scripts" / "check_standards.py"), "--manifest", str(path)], + cwd=tmp_path, capture_output=True, text=True, check=False, + ) + assert result.returncode == 1 + assert "standards verification failed: unsafe asset path" in result.stdout + assert "Traceback" not in result.stderr + + +@pytest.mark.parametrize("operation", ["resolve", "is_file", "read_bytes"]) +@pytest.mark.parametrize("error_type", [OSError, ValueError]) +def test_checker_cli_reports_asset_access_failures( + reference_checker, catalog_copy, monkeypatch: pytest.MonkeyPatch, capsys, operation: str, error_type, +) -> None: + """Filesystem failures are reported through the same command-line error contract.""" + path, _ = catalog_copy + + def fail(*args, **kwargs): + raise error_type("asset access failed") + + monkeypatch.setattr(Path, operation, fail) + assert reference_checker.main(["--manifest", str(path)]) == 1 + assert "standards verification failed: cannot" in capsys.readouterr().out + + +def test_checker_cli_reports_resolution_loops(reference_checker, catalog_copy, monkeypatch: pytest.MonkeyPatch, capsys): + """A filesystem resolution loop has the same failure status as other inaccessible paths.""" + path, _ = catalog_copy + + def fail(*args, **kwargs): + raise RuntimeError("symbolic link loop") + + monkeypatch.setattr(Path, "resolve", fail) + assert reference_checker.main(["--manifest", str(path)]) == 1 + assert "standards verification failed: cannot resolve asset path" in capsys.readouterr().out