Skip to content

Commit

Permalink
Preliminary rules.
Browse files Browse the repository at this point in the history 
  * Basic concepts and Core requirements
  * MUST UTF-8
  * comments are white spaces
  * anchored nodes are considered static
  * FAQ

Co-authored-by: Gregg Kellogg <[email protected]>
Co-authored-by: Ted Thibodeau Jr <[email protected]>
  • Loading branch information
@ioggstream @gkellogg @TallTed
3 people committed Jul 5, 2022
1 parent 13ff5f8 commit 1d2ffe5
Showing 1 changed file with 240 additions and 2 deletions.
242 changes: 240 additions & 2 deletions spec/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ <h2>Introduction</h2>
<p>
Since YAML is more expressive than JSON,
both in the available data types and in the document structure
(see I-D.ietf-yaml-mediatypes),
(see [[I-D.ietf-httpapi-yaml-mediatypes]]),
this document identifies constraints on YAML documents
such that they can be used to represent JSON-LD documents.
</p>
Expand Down Expand Up @@ -283,9 +283,156 @@ <h2>Introduction</h2>
<section id="basic-concepts" class="informative">
<h2>Basic Concepts</h2>

<p>FIXME.</p>
<p>
To ease writing and collaborating on JSON-LD documents, it is a common practice
to serialize them as YAML.
This requires a registered media type, not only to enable content negotiation
of linked data documents in YAML, but even to define the expected behavior of
applications that processes these documents, including fragment identifiers and
interoperability considerations.
</p>

<p>
This is because YAML is more flexible than JSON:
</p>

<ul>
<li>YAML supports different encodings, including UTF-8, UTF-16, and UTF-32.</li>
<li>YAML supports more data types than JSON.</li>
<li>the structure of a YAML document &mdash; that is, a named YAML representation graph &mdash;
is a rooted, directed graph that can have cycles.</li>

<p>
The first goal of this specification is to allow a JSON-LD document to be
processed and serialized into YAML, and then back into JSON-LD, without
losing any information.

This is always possible, because a YAML representation graph can always represent
a tree, because JSON data types are a subset of YAML's, and because
JSON encoding is UTF-8.
</p>

<p data-format="markdown>Example: the JSON-LD document below
```
{
"@context": "http://example.org/context.jsonld",
"@graph": [
{"@id": "http://example.org/1", "title": "Example 1"},
{"@id": "http://example.org/2", "title": "Example 2"},
{"@id": "http://example.org/3", "title": "Example 3"}
]
}
```

can be serialized as YAML as follows.
Note that entries
starting with `@` need to be enclosed in quotes or escaped because
`@` is a reserved character in YAML.

```yaml
%YAML 1.2
---
"@context": http://example.org/context.jsonld
\@graph:
-
"@id": http://example.org/1
title: Example 1
-
\@id: http://example.org/2
title: Example 2
-
'@id': http://example.org/3
title: Example 3
```


</p>
</section>
<section id="specifications" class="normative">
<h2>Core Requirements</h2>

<p>
A YAML-LD document is a [[YAML]] document that can be interpreted as Linked Data [[LINKED-DATA]].
</p>
<p>
It MUST be encoded in UTF-8, to ensure interoperability with [[JSON]].
</p>
<p>
Comments in YAML-LD documents
are treated as white space
This behavior is consistent with other
Linked Data serializations like [[TURTLE]].
See Interoperability considerations of [[I-D.ietf-httpapi-yaml-mediatypes]]
for more details.
</p>
<p>
Since named anchors are a serialization detail,
such names
MUST NOT be used to convey relevant information,
MAY be altered when processing the document,
and MAY be dropped when interpreting the document as JSON-LD.
</p>
<p>
A YAML-LD document MAY contain named anchors and alias nodes,
but its representation graph MUST NOT contain cycles.
When interpreting the document as JSON-LD,
alias nodes MUST be resolved by value to their target nodes.
</p>
<p data-format="markdown">
Example: The following YAML-LD document
contains alias nodes for the `{"@id": "country:ITA"}` object:

```yaml
%YAML 1.2
---
"@context":
"@vocab": "http://schema.org/"
"countries": "http://publication.europa.eu/resource/authority/country/"
"@graph":
- &ITA
"@id": countries:ITA
- "@id": http://people.example/Homer
name: Homer Simpson
nationality: *ITA
- "@id": http://people.example/Lisa
name: Lisa Simpson
nationality: *ITA
```

While the representation graph (and eventually the in-memory representation
of the data structure, e.g., a Python dictionary or a Java hashmap) will still
contain references between nodes, the JSON-LD serialization will not.

```json
{
"@context": {
"@vocab": "http://schema.org/",
"countries": "http://publication.europa.eu/resource/authority/country/"
},
"@graph": [
{
"@id": "countries:ITA"
},
{
"@id": "http://people.example/Homer",
"full_name": "Homer Simpson",
"country": {
"@id": "countries:ITA"
}
},
{
"@id": "http://people.example/Lisa",
"full_name": "Lisa Simpson",
"country": {
"@id": "countries:ITA"
}
}
]
}
```
</p>
</section>
<section id="sec" class="informative">
<h2>Security Considerations</h2>

Expand Down Expand Up @@ -423,5 +570,96 @@ <h3>Examples</h3>
</section>
</section>

<section id="faq" class="informative" data-format="markdown">
<p class="ednote">REMOVE THIS SECTION BEFORE PUBLICATION.</p>

<h3>FAQ</h3>

#### Why does YAML-LD not preserve comments?
<p class="ednote">
[[JSON]] (and hence [[JSON-LD]]) does not support comments,
and other Linked Data serialization formats
that support comments (such as [[TURTLE]])
do not provide a means to preserve them
when processing and serializing the document
in other formats.
The proposed behavior is thus consistent with
other implementations.

While YAML-LD could define a specific predicate for comments,
that is insufficient because, for example,
the order of keywords is not preserved in JSON, so the
comments could be displaced.
This specification does not provide a means for preserving
YAML comments after a JSON serialization.

```yaml
# First comment
"@context": "http://schema.org"

# Second comment
givenName: John
```

transforming the above entry into a JSON-LD document
results in:

```json
{
"@context": "http://schema.org",
"givenName": "John"
}
```


#### Why does YAML-LD not extend the JSON-LD data model ?
<p class="ednote">
[[JSON]] only represents simple trees while [[YAML]] can support
rooted, directed graphs with references and cycles.

The above structures cannot be preserved when serializing
to JSON-LD and - with respect to cycles - the serialization
will fail.

Programming languages such as Java and Python already support
YAML representation graphs, but these implementations may behave
differently.
In the following example, `&value` references the value
of the keyword `value`.

```yaml
value: &value 100
valve1:
temperature: &temp100C
value: *value
unit: degC
valve2:
temperature: *temp100C
```

Processing this entry in Python, I get the following
structure that preserve the references to
mutable objects (e.g., the `temperature` dict)
but not to scalars (e.g., the `value` keyword).

```python
temperature = { "value": 100, "unit": "degC" }
document = {
"value": 100,
"valve1": { "temperature": temperature },
"valve2": { "temperature": temperature }
}
```

Since all these implementations pre-date this
specification, some more interoperable choices include the following:

* to forbid cycles in YAML-LD documents
* to consider all references in YAML-LD as static,
i.e., a shorthand way to repeat specific patterns

</p>
</section>

</body>
</html>

0 comments on commit 1d2ffe5

Please sign in to comment.