json-ld / yaml-ld

CG specification for YAML-LD and UCR
https://json-ld.github.io/yaml-ld/spec
Other
22 stars 8 forks source link

YAML-LD UCRs #2

Closed VladimirAlexiev closed 2 years ago

VladimirAlexiev commented 2 years ago

Related to https://github.com/w3c/json-ld-syntax/issues/389, https://github.com/json-ld/yaml-ld/issues/3. TODO: scan these issues to extract more requirements.

Like any great W3C work, we should start with a Use Case Requirements specification / collection.

Until we have a repo (@gkellogg) where we can collect UCR per issue, let's use the following format. It could help UCR editors collect the issues:

Notes:

Here we go


instead of long form

dc:date: @type: xsd:date @value: 2022-05-18


- [x] COULD: Polyglot Modeling #19
  - For efficient RDF modeling, you need to define multiple related artefacts: ontology, shapes (SHACL (@holgerknublauch) or SHEX (@ericprud)), JSON-LD context, maybe JSON-LD frames, JSON schema or Avro schema
  - Many communities like LD expression of their data, but mostly care about defining it with JSON schema (eg `w3c-ccg` @OR13 @nissimsan @msporny)
  - Many people have expressed the desire to define a unified or "technology independent"
  - Most polyglot frameworks are YAML-based. Examples include:
    - [LinkML](https://linkml.io/) ([github](https://github.com/linkml)) (@cmungall)
    - [FHIR](https://www.hl7.org/fhir/) (@ericprud: this is not YAML-based, can you provide a link to implementation?)
    - [Schema Salad](https://www.commonwl.org/v1.2/SchemaSalad.html) (@mr-c @tetron)
    - [A.ML](https://a.ml/) and [cloudinformationmodel](https://cloudinformationmodel.org/about.html)
    - [SOML](https://platform.ontotext.com/3.0/soml/index.html) (@VladimirAlexiev)
  - See eg https://github.com/w3c-ccg/traceability-vocab/issues/296 for a brief list of modeling framework requirements
  - YAML-LD should not take over these modeling-framework efforts, but should show how they can be used together, show archetypical examples, and maybe make a comparison
- [x] #20
  - YAML-LD must include comprehensive conformance tests for all its features.
  - In fact the features should be designed after agreed archetypical examples, so it's feasible for the development process to be "test-driven"
  - It should replicate/re-render all JSON-LD tests. Despite no official support in the spec, the gazillion JSON-LD conformance tests are written in YAML: https://github.com/w3c/json-ld-syntax/tree/main/yaml 

- [x] SHOULD #42 
- [x] MUST #43
ioggstream commented 2 years ago

While working on +yaml media type definition for expressing json files (openapi+yaml, ld+yaml, ..) we provided some interoperability considerations in https://ietf-wg-httpapi.github.io/mediatypes/draft-ietf-httpapi-yaml-mediatypes.html

We are engaging with YAML community via https://app.element.io/#/room/#chat-mediatype:yaml.io and it could be useful to discuss specific points together.

OR13 commented 2 years ago

We generate JSON-LD contexts from Open API Specifications in YAML here:

https://w3c-ccg.github.io/traceability-vocab/openapi/

For example:

We invented a syntax for describing JSON-LD terms in JSON-Schema:

$linkedData:
  term: AgActivity
  '@id': https://w3id.org/traceability#AgActivity
title: Agricultural Activity

This allowed us to define an RDF type and a JSON Schema type in the same file, which helps us keep semantics and security in sync.

ioggstream commented 2 years ago

We invented a syntax for describing JSON-LD terms in JSON-Schema:

OT: @OR13 we are working on similar stuff, but with a different syntax after some analysis since we need to be compatible with OAS3.0 ( x-jsonld-context and x-jsonld-type). Here's an editor that does the mapping https://ioggstream.github.io/swagger-editor/

ericprud commented 2 years ago

The semantics of ShEx is defined in terms of its JSON(-LD) representation (e.g. value sets). I've so far relied on js-yaml to have the one true mapping from JSON to YAML in lirbaries like ShapePath. We'd brought up the idea of a YAML representation (which would, of course, be named "ShExY"), but since the translation was so trivial, we never found conflicts between the ways we wrote or interpreted ShExY. That said, if JSON-LD defined this, there'd be no need.

OR13 commented 2 years ago

Sounds like we have a few different things happening:

  1. JSON-LD -> YAML (objects with a @context)
  2. JSON-LD Shape (shex) -> YAML shape (shexy)
  3. JSON Schemas in YAML -> JSON-LD Context

(I think 3 might be a bit more different than 1 and 2).

I will elaborate a bit more on the why "why".

Most of the JSON-LD contexts we've seen have gotten really, really large... that made them really hard to maintain / test.

We set out to be able to test each RDF Type independently, and using JSON Schema as the base, since folks are used to composing JSON Schemas to manage complexity.

As a side effect, this allowed us to compose JSON Schemas to manage context complexity.

I suppose there are other tools we could have used to do this, but we picked OAS and JSON Schema because of their appeal to "non linked data people"... we've observed there are a lot off folks that stumble when they first encounter JSON-LD, we thought it would be good to give them smaller building blocks that were more familiar to them.

ioggstream commented 2 years ago

I think that since YAML 1.2 flow serialization "seems" JSON, it is almost impossible to define an ld+yaml that does behave in a different way from what the general audie ance expects.

Probably the only extension points (which do not have a JSON counterpart) are:

In general, I think that interoperability should be a concern since many implementations prefer serializing everything to JSON to avoid managing cyclic graph processing issues et al at runtime.

gkellogg commented 2 years ago

Repo has be set up at https://github.com/json-ld/yaml-ld. If you would like to contribute, and are a member of the JSON-LD Community Group I can add you to the contributors team. Please create an issue (or respond to an already existing issue) to be added to the team.

gkellogg commented 2 years ago

Moving this issue to the yaml-ld repo.

OR13 commented 2 years ago

Primary reason I am interested in YAML-LD is small, composable, human readable RDF definitions for the modern era.

Compatibility with JSON-LD is good, but I think we should be wary of giving YAML-LD the same amount of rope that JSON-LD supports, and we should make sure that all the benefits of YAML are available to RDF, not just the parts of YAML that translate directly to JSON.

ericprud commented 2 years ago
* [FHIR](https://www.hl7.org/fhir/) (@ericprud: this is not YAML-based, can you provide a link to implementation?)

@VladimirAlexiev , https://github.com/hapifhir/hapi-fhir is a prominent open-source Java server. As you osberved, there's no FHIR/YAML (though we make use of it in the build process).

I'll delete this comment once you ack it.

VladimirAlexiev commented 2 years ago

@ericprud acked but why delete? Cheers!

VladimirAlexiev commented 2 years ago

Closing this; I'll gradually move bullets from description to separate issues. If you've made important considerations in comments above, please post them as separate issues.

@OR13 and @cmungall, would you like to add something to #19?

VladimirAlexiev commented 2 years ago

@gkellogg Can we use this issue somehow to track the completeness of https://github.com/json-ld/yaml-ld/pull/37?

ioggstream commented 2 years ago

@VladimirAlexiev I think as of now it would be useful to complete a first draft and start closing some issues. Without a document stub, other folks cannot understand what we are doing.

With the "profiling" idea we will be able to accomodate more and more use cases #35

gkellogg commented 2 years ago

@gkellogg Can we use this issue somehow to track the completeness of #37?

As this issue is closed, probably not the best place to track anything. If you want to use this use case for tracking milestones, then it should be re-opened. Or, we should look into GitHub Milestones.

  • can you edit the description? (I can even edit comments in this project, so you should be able to do to the same)

PR #37 is just a point in time, more use cases will certainly be forthcoming, and we'll need to figure out how to reconcile conflicting use cases.

Presumably, the "Requirements" part of UCR should describe how the spec should address a given use case, of if the use case has been rejected.

ioggstream commented 2 years ago

Create two milestones: -00 and -future