search

Informatievlaanderen / registry-documentation

All documentation related to the base registries.
https://informatievlaanderen.github.io/registry-documentation/
1 stars 2 forks source link

JSON-LD Support #7

Open CumpsD opened 3 years ago

CumpsD commented 3 years ago

JSON-LD 1.1

Goal

In a future version of the registries we have to output valid JSON-LD 1.1 documents. These are regular JSON responses with the addition of a @context property to provide a mapping between JSON properties and LD PURI's.

Preferably we want to keep the source the authoritative source of this mapping. While at the same time reducing the amount of work needed.

Ideas

Investigate Compaction/Expansion

JSON-LD provides algorithms for Compaction and Expansion. Have a look if these are useful for us?

Investigate Generation

Have a look if we can take an existing @context file and generate C# code from it to be used in attributes later on.

TODO

Result

Compaction/Expansion

These algorithms primary purpose are to take an existing @context and apply them to an existing JSON-LD document in order to either clean up the document (compaction), or make it more verbose (expansion).

In our case, this simply overcomplicates things. We want to either generate a @context with only the properties used in a response or/and have a fault-tolerant way to use the correct property names to make sure the mapping stays correct.

Generation

We have made a tool to generate a static class with constants on it for each property in a @context file. These can then be used as follows:

[PropertyName(Constants.Adres.Status)]
public string Status { get; set; }

Further research will tell us if we need to generate more things, different things, or if this is enough.

Challenges

Context files out of our control

Since the existing context files are created and managed by another team, we are at their mercy. This has shown to cause problems with regards to URLs changing and content changing. In other words, there is a strong need for versioning of context files.

ArneD commented 3 years ago

Which version to use for json-ld? 1.0 or 1.1? If 1.0 is anything holding us back for going to 1.1?

ArneD commented 3 years ago

Libraries have functions like expand, compact, flatten or frame. Issue https://tinyurl.com/y2t4vwmx

As you can see the json-ld provided has a lot more info than any of those 4 functions return. Such as _links or identificator. So maybe we won't be able to use a library at all.

ArneD commented 3 years ago

Versioning of data.vlaanderen.be is a must!