Clarification on IRI Usage for Related Resources in the Ontology

[arruda]

Hi @rapw3k and Jack.

I'm very new to using JSON-LD, so I wanted to clarify how to handle references to related resources, specifically the use of IRI (Internationalized Resource Identifier) versus embedding full object data (or support for both?).

In our use case, we have entities like FarmAnimal and FarmArea that represent models in our database. A FarmAnimal has a foreign key reference to a FarmArea, and we want to know the best way to handle this relationship in JSON-LD while conforming to the ontology schema.

It is common in a REST API to have a Hyperlink reference for this case, so in a common JSON an given FarmAnimal that is registered in the FarmArea "XYZ" would return, something like:

{
   "name": "A Cow",
....
   "area": "https://farmcalendar:8002/api/farmArea/XYZ"
}

And if someone wanted information about this animal farm area then then can get this hyperlink reference to the area and do a GET request on "https://farmcalendar:8002/api/farmArea/XYZ".

Now, if I understand correctly from the examples (how the farm profile references a farm area), it is not by the IRI right?

So my question is: Can we somehow add this support to our schema, so that returning a IRI of the farmArea instead of all the farm area details is still valid? and if already has that support, how is this relationship presented in the json-ld? do we "change" the FarmArea property type in the context to be of the type ID instead of "Vineyard" or "Pasture" or something like that?

PS: ignore the names like FarmAnimal and FarmArea for now; I still need to change this to the same names as the ones in the ontology.

[JackJackUM]

Hi @arruda Felipe: let me see if I understand your question correctly.

It is not common (unfortunately) to have a clickable IRI that you can follow to get more info on a specific resource. So, when you receive the IRI via some call (query or get-operation) to an API, you need to use that IRI in a subsequent call to that API to get more info on the resource.

When it comes to JSON-LD, the JSON-LD schema should define the @type of the resource of the IRI that is provided and which properties are required to be provided. With that type, you can see in the underlying ontology of which class the resource is and which properties the class has. These can be datatype properties (to string, integer, etc.) or object properties to other classes in the ontology. So, using this JSON-LD schema you must be able to get full insight in what you can request and will receive.

Have a look at my email in which I attached the fertilization.yaml file that represents the JSON-LD schema of a fertilization record. I'm trying to push this file to the OpenAgri-eu repo, so that it will be available for all of us.

Is this what you mean and did I answer your question?

[arruda]

Thanks @JackJackUM it really helped! I was confusing the roles of the schema and the ontology, now it is much clearer to me.

It is not common (unfortunately) to have a clickable IRI that you can follow to get more info on a specific resource. So, when you receive the IRI via some call (query or get-operation) to an API, you need to use that IRI in a subsequent call to that API to get more info on the resource.

Yes, I get that, I was just a bit confused since when I saw some of the schema files they didn't seem to have IRI refs (e.g., json-schema/ocsm-farmProfile.schema.json

Now, this brings me the question: are we going to have a general schema for all services (defined in this repository as well), or we'll be working with different schemas on each service?

[JackJackUM]

Maybe superfluous...but if you now look at the fertiliization.yaml you will see the schema of a fertilization JSON-LD file. In there, you see that each @id is of type string with format iri.

So trying to summarize:

• The ontology defines the concepts and their relations as classes and properties
• A JSON-LD schema defines the structure of a JSON-LD "file". The schema should adhere to the ontology in the sense that the types of objects, their properties and related objects are as defined in the ontology
• A JSON-LD file should adhere to its schema and can be the output/result of an API GET operation or input/output of an API POST operation.

So, when we define the API of an OpenAgri service that produces a JSON-LD result/output, we should describe the JSON-LD schema that defines the JSON-LD structure of the output. Thereby, everyone can have a look at the schema's and know what to expect as output from the API.

Hope this helps!

Cheers, Jack

[arruda]

Thanks, @JackJackUM. This clarification on the roles of the ontology, json-ld schema, and payload really helped me understand what is what. I'll keep refactoring the farmcalendar to use already the OCSM names for the models in there, and once I have a first version of a json-ld payload I'll paste it here to check with you guys if it seems correct.