From 30258239f3322f4e0ac64b280e7b74a2109de929 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Fri, 24 Jun 2022 11:52:17 -0700 Subject: [PATCH] Apply suggestions from @ioggstream. --- spec/index.html | 98 +++++++++++++++++++------------------------------ 1 file changed, 38 insertions(+), 60 deletions(-) diff --git a/spec/index.html b/spec/index.html index 9f85332..4e9a96e 100644 --- a/spec/index.html +++ b/spec/index.html @@ -10,12 +10,30 @@ copyrightStart: "2020", shortName: "yaml-ld", edDraftURI: "https://json-ld.github.io/yaml-ld/", - github: "https://github.com/json-ld/yaml-ld/", + github: { + repoURL: "https://github.com/json-ld/yaml-ld/", + branch: "main" + }, doJsonLd: true, editors: [{ name: "JSON-LD Community" }], + localBiblio: { + "I-D.ietf-httpapi-yaml-mediatypes": { + title: "YAML Media Type", + href: "https://datatracker.ietf.org/doc/draft-ietf-httpapi-yaml-mediatypes/", + publisher: "IETF", + date: "2022-06-23", + status: "WG Document", + authors: [ + "Roberto Polli", + "Erik Wilde", + "Eemeli Aro" + ] + }, + }, + // Cross-reference definitions xref: ["json-ld11", "json-ld11-api", "json-ld11-framing"], @@ -229,7 +247,8 @@

Introduction

this document identifies constraints on YAML documents such that they can be used to represent JSON-LD documents.

- + +

A YAML-LD document complies with this specification if ...

Define YAML-LD document somewhere.

@@ -270,7 +289,8 @@

Basic Concepts

Security Considerations

-

See the YAML media type registration.

+

See Security considerations in JSON-LD 1.1. + Also, see the YAML media type registration.

@@ -278,18 +298,19 @@

Interoperability Considerations

For general interoperability considerations on the serialization of - JSON documents in YAML, see [[YAML]]. + JSON documents in YAML, see [[YAML]] + and the Interoperability consideration of application/yaml [[I-D.ietf-httpapi-yaml-mediatypes]]..

-
+

IANA Considerations

This section has been submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA.

-

application/ld+json

+

application/ld+yaml

Type name:
application
@@ -315,20 +336,10 @@

application/ld+json

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 seven values for the profile parameter.

+

This specification allows the use of the `profile` parameters listed in + and additionally defines the following: +

-
http://www.w3.org/ns/json-ld#expanded
-
To request or specify expanded YAML-LD document form.
-
http://www.w3.org/ns/json-ld#compacted
-
To request or specify compacted YAML-LD document form.
-
http://www.w3.org/ns/json-ld#context
-
To request or specify a YAML-LD context document.
-
http://www.w3.org/ns/json-ld#flattened
-
To request or specify flattened YAML-LD document form.
-
http://www.w3.org/ns/json-ld#frame
-
To request or specify a YAML-LD frame document.
-
http://www.w3.org/ns/json-ld#framed
-
To request or specify framed YAML-LD document form.
http://www.w3.org/ns/json-ld#extended
To request or specify extended YAML-LD document form.
@@ -337,19 +348,9 @@

application/ld+json

making use of YAML-specific features.
-

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]], + in an HTTP Accept header field [[RFC9110]], 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 @@ -361,40 +362,17 @@

application/ld+json

Encoding considerations:
-
See RFC 8259, section 11.
+
See .
Security considerations:
-
See RFC 8259, section 12 [[RFC8259]] -

When processing YAML-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.

-

YAML-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 YAML-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 YAML-LD allows the substitution of long IRIs with short terms, - YAML-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 YAML-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.

-
+
See .
Interoperability considerations:
-
Not Applicable
+
Published specification:
http://www.w3.org/TR/yaml-ld
Applications that use this media type:
Any programming environment that requires the exchange of directed graphs. Implementations of YAML-LD have been created for - FIXME. + FIXME.
Additional information:
@@ -428,16 +406,16 @@

Examples

Fragment identifiers

-

Fragment identifiers used with application/ld+json +

Fragment identifiers used with application/ld+yaml are treated as in RDF syntaxes, as per RDF 1.1 Concepts and Abstract Syntax [[RDF11-CONCEPTS]]. -

Perhaps more on fragment identifiers from
+
Perhaps more on fragment identifiers from Issue 13

YAML media type support both alias nodes and JSON Pointers [[RFC6905]] - as fragment identifiers (see [[I-D.httpapi-yaml-mediatypes]]). + as fragment identifiers (see [[I-D.ietf-httpapi-yaml-mediatypes]]). Since named anchors are serialization details, when using alias nodes to reference nodes in external documents, the implementation needs to be confident that the serialization of