schemas must allow referencing in addition to nesting

[VladimirAlexiev]

If I'm not mistaken, the current schemas always specify nesting because you "include" other schemas.

In other words, you'd force me have this payload:

  id: did:example:BillOfLading:1234
  type: BillOfLading
  consignor:
    type: Entity
    id: did:web:ontotext.com
    name: Ontotext
    phone: blah

  id: did:example:Product:4321
  type: Product
  name: Ontotext GraphDB
  manufacturer: 
    type: Entity
    id: did:web:ontotext.com
    name: Ontotext
    phone: blah

But I'd much rather have this:

  id: did:web:ontotext.com
  type: Entity
  name: Ontotext
  phone: blah

  id: did:example:BillOfLading:1234
  type: BillOfLading
  consignor: did:web:ontotext.com

  id: did:example:Product:4321
  type: Product
  name: Ontotext GraphDB
  manufacturer: did:web:ontotext.com

Companies are certainly no less important than their products and shipping documents, so they deserve to have top-level nodes of their own.

JSONLD allows nesting, referencing, or combinations (e.g. I can nest the first instance in BillOfLading, and reuse it in Product).
But IMHO your schemas allow only nesting.

[VladimirAlexiev]

On second thought: I think you want your schemas to be quite inflexible for easier interoperation.

• If so, we should change the title to
  schemas should use referencing instead of nesting for all important objects
• instead of the current
  schemas must allow referencing in addition to nesting

[OR13]

@nissimsan @BenjaminMoe can you propose some concrete action regarding this?

[nissimsan]

This reminds me of XML vs XML-RDF.

[VladimirAlexiev]

@nissimsan XML-RDF is the worst RDF serialization because you can express the same graph using a variety of XMLs
(the graph-tree transformation doesn't dictate where to start and which nodes to render embedded),
and people try to process it using XSLT, and hit a wall or create overly limited solutions.

---

I'll copy a comment from #290 that's more salient here:

Every time you have a JSONLD sub-object or a textual ID, you could have a URL.
That URL can carry semantic data in a variety of places:

1. in the same JSON position, or
2. in another position (top level or another sub-object)
3. in external payload from referencing the URL

How can JSON Schema handle this variety?
All your current schemas favor 1 (embedded subjects), but that facilitates data copying not data sharing.

And copied data is outdated data.

---

@OR13 @BenjaminMoe In other words, the current schemas are over-optimized for messages.
But semantic data lives in graphs, that are potentially distributed.

If you agree with the importance I attach to this issue then we need to:

• Decide which objects can live at top level or externally (first-class objects), and which are only ever embedded (second-class slaves)
• Decide that first-class objects must be identified by URL
  • Eg for a LOCODE-identified place, you need to pick a LOCODE URL scheme, even if uncefact isn't quite ready for that
  • For GLNs, you must adopt the GS1 convention that GLNs will be expressed as URLs not URNs, at the GS1 resolver or company sites
• Rework all schemas to allow referencing first-class objects. IMHO it'll be simpler to postulate them only at top-level, or externally served

[nissimsan]

Hi @VladimirAlexiev,

To be clear, I'm not advocating for XML-RDF, just pointing out the hierarchy vs flat structure with references similarity.

First, schema and example/instance seems conflated throughout this ticket. The original point was to define schemas by means of URL references, but the example includes instance-identifiers (did:example:BillOfLading:1234) and you also talk about "outdated data"? Are we talking about schema or instance?

Second, you originally headed in the direction of "On second thought: I think you want your schemas to be quite inflexible for easier interoperation." which I find is an important argument. We are intentionally doing both JSON Schema and LD. What you are advocating here is more of a pure LD approach(?) I think this is a dangerous path in terms of adoption. There are orders of magnitude more developers in the world comfortable adding a JSON Schema to an API than those comfortable carving out and merging data graphs. We might not have a well articulated strategy on this part, but the approach of "just use this JSON Schema and get LD for free" quite powerful, bridging the the traditional API world with the brave new graph world. I can live with the limitations of lowest common denominator of LD and JSON Schema in the attempt to reach this goal. We have to be gentle. And the world is full of locked down business processes with defined messaging anyway.

[brownoxford]

We are currently not planning on supporting anything other than OpenAPI specification v3.

[OR13]

I suggest we stick to using OAS 3.0

[nissimsan]

Agreed. While the normalized flat structure with references looks very attractive, the world is full of developers who can intuitively pick up a hierarchical JSON. That is our primary audience.

[nissimsan]

Typically issuer organzation is also represented elsewhere on the credential. Like the (issuing) Carrier on a BL.
I'll make an example for this and a proposal on how to go about it.