Jargon for JSON-LD — A worked example using schema.org
Jargon is a platform for creating data models and APIs using Domain Driven Design.
We’ve recently added the ability to export your Domains as JSON-LD vocabularies. Let’s take a look at how to do it.
What we will be creating
For this example, we will be recreating the PetStore example from Swagger, but will leverage types from schema.org where they exist.
Importing Schema.org
Jargon maintains an internal Domain of Schema.org’s vocabulary. It was imported from JSON-LD, and isn’t perfectly accurate, but is an excellent starting point for accessing Classes and Properties from schema.org.
You can take a look at Jargon’s version of Schema.org on the public Jargon instance.
There’s nothing special about how Jargon treats the schema.org domain — you can import it and use properties from it just like any other Domain on Jargon. There’s a guide on how to import Domains here.
Starting with the PetStore example
Whenever you create a new Domain, Jargon offers to populate it with an example Domain that is based on the Swagger PetStore Domain. We’ll be using this as our starting point:
After taking the sample Domain and importing schema.org, I’ve clicked on the Import Tree button (the highlighted blue icon in the top right of the above image). This brings up Jargon’s pane for searching and using imported Classes and Properties — we’ll be primarily using this to navigate through the schema.org Domain, as it’s really very big.
Using Schema.org Classes and Properties
The Tree of Imported Classes pane lists out all the Domains (including the one we’re editing) that have been imported, their Classes and Properties.
Let’s see if schema.org has a better definition for Order.id.
If you know where to look, you can expand the tree to find the Class or Property that you’re after. Since schema.org is so big, I’ll instead filter all the imported Classes and Properties in this domain, which will give me a shortlist of what I’m after.
Entering ‘order’ into the filter box and hitting enter brings up these results:
It looks like there’s an Order class in schema.org, and one of it’s Properties is orderNumber — which sounds exactly what we’re after.
If this was a new Property we were adding, I could click the icon next to ‘schema.Order.orderNumber’, and Jargon would insert this Property into the model. Because we already have an Order.id property, I’ll just copy text in the white box, which Jargon has calculated using the prefix that I imported Schema.org with: ‘schema.Order.orderNumber’, and paste it over the existing type for Order.Id (which was Numeric):
So what’s just happened here? We’ve told Jargon that the type of Order.id, is now ‘schema.Order.orderNumber’ — which is the orderNumber Property, of the Order class, within the schema imported Domain.
Following this process, we can replace the rest of the types in our Domain, and whilst I’m no schema.org expert, I’m pretty happy with the result:
Enabling JSON-LD
You need to configure Jargon to enable JSON-LD generation, which you can do on the Domain’s settings page. After clicking the ‘Generate JSON-LD’ checkbox (and saving the settings) the next time you save your Domain, Jargon will generate the JSON-LD vocabulary and context file for you.
In the JSON-LD settings, you can also change the prefix and vocabulary URI, if you know that you are going to be publishing your JSON-LD somewhere.
Wrapping up
That’s how you can create JSON-LD vocabularies in Jargon, and how you can reference Classes and Properties from schema.org. You can import and reference any Domain in Jargon, and if a Domain you have imported has configured their JSON-LD settings with a prefix and vocabulary URI, Jargon will use those to point to the published vocabulary.
The Domain from this article is available on the public Jargon instance, along with the JSON-LD Vocabulary and context file.
If you’re interested in getting started with Jargon, or JSON-LD, why not create a free account and try it out.
If you have any questions, or spot any errors, please:
- leave a comment below, or
- raise an issue at the jargon issue tracker GitHub repository
