W3C YAML-LD

[westurner]

STORY: Users can reformat YAML-LD with yamlfmt per the YAML-LD/JSON-LD guidelines.

• Src: https://github.com/json-ld/yaml-ld
• Spec: https://json-ld.github.io/yaml-ld/spec/
• Tests: https://github.com/json-ld/yaml-ld/tree/main/tests
• Tests: https://github.com/json-ld/yaml-ld/blob/main/tests/basic/cir-scalar-core-1-positive-in.yamlld

[westurner]

From https://json-ld.github.io/yaml-ld/spec/#example-convenience-context ::

EXAMPLE 7: Convenience Context
Code of the convenience context. Available as: https://github.com/json-ld/convenience-context.

{
  "@context": {
    "$base": "@base",
    "$container": "@container",
    "$direction": "@direction",
    "$graph": "@graph",
    "$id": "@id",
    "$import": "@import",
    "$included": "@included",
    "$index": "@index",
    "$json": "@json",
    "$language": "@language",
    "$list": "@list",
    "$nest": "@nest",
    "$none": "@none",
    "$prefix": "@prefix",
    "$propagate": "@propagate",
    "$protected": "@protected",
    "$reverse": "@reverse",
    "$set": "@set",
    "$type": "@type",
    "$value": "@value",
    "$version": "@version",
    "$vocab": "@vocab"
  }
}

The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 specification permits aliasing — which means all the keywords except @context. The reserved @ character is replaced by $, which is not reserved and therefore does not require quoting.

[westurner]

How should yamlfmt format YAML-LD YAML documents?

• sort attrs by key
• normalize "@id" / $id (if this is what the spec guidelines say)
• "@context": should be at the top of the document
• reframe/compact/expand the underlying JSON-LD graph
  • https://json-ld.org/playground/ has {Expanded, Compacted, Flattened, Framed,} JSON-LD 'compactions'(?)
    • Compact serialization RDFLib/rdflib-jsonld#93
    • https://www.w3.org/TR/json-ld11-framing/#framing-0

      The following sections describe algorithms for framing JSON-LD documents. Framing is the process of taking a JSON-LD document, which expresses a graph of information, and applying a specific graph layout (called a Frame).

[braydonk]

Hi @westurner thanks for the feature request. This sounds like it deviates heavily enough from a normal yaml document that it should likely be implemented as a separate formatter that the user can choose to use instead of the current basic one.

I will not have time to implement this any time soon unfortunately, but if anyone in the community wanted to I am happy to help explain how to design it to satisfy the interface and hook into the rest of yamlfmt (I don't have any developer docs yet only user ones).

[westurner]

TBH IDK when I'll have time for this priority either. Are there links to sources that would help? How should the CLI args work (there are probably addl YAML-LD args beyond --formatter=yamlld; rdfpipe supports a few but pyld is the python reference implementation of JSON-LD and it has tests for CLI args IIRC)

…

On Sun, Jul 16, 2023, 9:50 PM Braydon Kains ***@***.***> wrote: Hi @westurner <https://github.com/westurner> thanks for the feature request. This sounds like it deviates heavily enough from a normal yaml document that it should likely be implemented as a separate formatter that the user can choose to use instead of the current basic one. I will not have time to implement this any time soon unfortunately, but if anyone in the community wanted to I am happy to help explain how to design it to satisfy the interface and hook into the rest of yamlfmt (I don't have any developer docs yet only user ones). — Reply to this email directly, view it on GitHub <#125 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMNS3NGHBTPGPWOXRN3ATXQSK6VANCNFSM6AAAAAA2LLKEMY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[braydonk]

It depends what kind of help you'll need. If it's about actually implementing the formatter interface, I have not actually documented how it works but I don't think it's too tough. Development docs have always been low priority cause I haven't had anyone trying to use the libs a whole lot yet (at least that I've heard about). I am happy to help guide how to do that, and it'll help me actually write some docs along the way too.

Unfortunately I don't know much about YAML-LD; had never heard of it before you opened this issue here 😄
So I can't say for sure whether this will need an entirely new yaml parser or if it could be done using some fancy rearranging on the Node type used by the yaml library in the basic formatter. The basic formatter turns the whole document into an array of Nodes that recursively contain all the others, and the formatter supports applying basic transformations on it.

If it will require a new parser due to some difference in YAML-LD syntax, then it would be best implemented as a separate formatter that used its own parser. This ends up just getting down to how to write parsers in general. There are 2 solid yaml libraries in Go, yaml.v3 and go-yaml that could serve as reference or basis for a fork.

The way formatter options work in general is that they are completely independent of each other. So a hypothetical yaml-ld formatter would have its own set of configuration options, and these would be specified either in the .yamlfmt config file, or in the -formatter flag (see docs for info). There would need to be another flag that actually supports changing to the right formatter; currently there is only one, so a flag to choose a different formatter doesn't exist right now but I can easily add it if it becomes necessary.

Hopefully this helps a bit, I'm happy to connect directly if you or anyone else wanted to take this work on.

[westurner]

There probably doesn't need to be a new parser just to normalize quoting, optionally replace @ with $, and sort attrs with @context and then $id $type etc at the top?

With standard ASCII (and thus also Unicode) collation, IIRC $ is before A but @ is not, so @context will not be at the top of a json/yaml doc after e.g. cpython's json.dumps(sort_keys=True).

• https://en.wikipedia.org/wiki/ASCII#Character_order
• https://en.wikipedia.org/wiki/Collation

(Also, FWIW, Gmail mobile and Gmail web have different collation orders for sorting labels; @ <=> $)

[braydonk]

If the YAML-LD can properly conforms to YAML 1.1 spec then it's possible to do this in the existing formatter and do the transformations on the yaml.Node structure from the parsed document. (I make no promises about the ergonomics of that structure, I've never worked with it in a way where I've tried to transform and it might be okay or it might be super asinine)