I'm just creating the schema code for my aboutme-page, where I introduce myself and my professions. I'm an alternative healer. Person is (and should remain, if possible) the top-level-item. On the aboutme-page I have referenced my legal state permission by linking to a digital copy on my site (.jpg).
The code I have created so far:
"#type": "Person",
"hasOccupation": {
"#type": "Occupation",
"name": "alternative healer",
"educationRequirements": {
"#type": "EducationalOccupationalCredential",
"credentialCategory": "state permission for alternative healers"
"recognizedBy": {
"#type": "GovernmentOrganization",
"name": "(name of government agency)"
},
"license": "(Wordpress-URL of state permission as .jpg)"
}
}
}
Is this code correct regarding the last property license, which should connect to the digital copy as an linked .jpg? Is it understandable this way for search engines that this digital copy is my concrete state permission and not any sample?
Would it be better to use url or image as understandable connection to my permission, instead of license? Or DigitalDocument?
The license property gives the license (e.g., as in copyright license) that applies to the creative work. It’s not for any kind of thing that gets called license.
Your EducationalOccupationalCredential represents the legal state permission license; if you provide a license property, it would be for giving the license (e.g., copyright) of the license (legal state permission).
To provide the digital file, you can use one (or several) of these ways:
associatedMedia/encoding - this allows you to provide metadata about the file
image - can be just the URL, or also an object that allows you to provide metadata about the file
url - this doesn’t allow you to provide metadata about the file
Related
I'm using FHIR R4 with Hapi FHIR API.
I want to know how marked the ServiceRequest resources with information about created user.
I've read the FHIR documentation and I've found the relevantHistory tag where I can put there a Provenance reference.
All good but the HAPI Fhir can't query that field/tag so I can't get all ServiceRequests created by me or another user.
I've also tried to use a customize extension named tracking, where I've put the tracking user info.
I don't want to use a requester tag because, it is filled with other guide line meaning supplied by customer
EDIT AFTER Mirjam Baltus
Hi,
interesting your point of view but, I've found another solution as follow, I want to discuss it with you (if you want).
I've added a SearchParameter resource attached on ServiceRequest to allow the search on relevantHistory field.
This is the JSON resource:
{
"resourceType": "SearchParameter",
"id": "6589",
"meta": {
"versionId": "7",
"lastUpdated": "2021-02-25T11:25:25.549+00:00",
"source": "#1btUOFbG0D3dMdwI"
},
"title": "Storia",
"status": "active",
"code": "relevantHistory",
"base": [
"ServiceRequest"
],
"type": "reference",
"expression": "ServiceRequest.relevantHistory",
"xpathUsage": "normal",
"target": [
"Provenance"
],
"modifier": [
"missing"
],
"chain": [
"reference"
]
}
So I've written a query on ServiceRequest filtered by relevantHistory field (linked to Provenance).
I've adopted this strategy because I need to know only the creator of ServiceRerquest, so in this way, I've factorized the information in Provenance resource where in the target field I've put the Practitioner / Organization who created the ServiceRequest and in the agent component I've replicated this information with ENTERER value in the enum AgentRole and AgentType.
In this way, I've collected one Provenance for more ServiceRequests, instead If I follow your way, I'll have for each ServiceRequest a dedicated Provenance.
You think I've followed a wrong way or it is a possible solution?
The relevantHistory is not the right field to use, since that will only list older Provenance resources that hold relevant information. The description specifically says it does not hold the Provenance resource associated with the current version of the ServiceRequest (see http://hl7.org/fhir/servicerequest-definitions.html#ServiceRequest.relevantHistory).
I think Provenance can still help you. You would not search on a field in ServiceRequest, but find ServiceRequests that have a Provenance where you/user are the actor:
GET [base]/ServiceRequest?_has:Provenance:target:actor=[user_reference]
Or approach it the other way around, by looking for Provenance resources from the user, and including ServiceRequests that are the target of the Provenance.
Added after edit of original post:
As I mention in my comment, I think the way you are trying to use the relevantHistory field and one Provenance for multiple ServiceRequests is not according to how that field and resource type are supposed to be used.
If you are able to create a custom search parameter, why not use an extension on the ServiceRequest to indicate who created it, and then make that extension searchable?
If you want more discussion about this, please ask on https://chat.fhir.org, where more people from the FHIR community will be able to chime in.
We intend to use Spring-HATEOAS to enrich our interface with hypermedia informations via HAL/JSON.
What we are wondering is, how to provide sufficient meta information of what we are going to find in a resource after following a link.
I identified different methods to publish such information, with one being the content type of the resource and the other being a profile.
However both do not allow any kind of polymorphism.
Let's assume we model a weather station which has a temperature a wind and a light sensor.
In my concept I would link those three sensors:
"item" : [
{ "href" : ".../sensors/1" } // temperature
{ "href" : ".../sensors/2" } // wind
{ "href" : ".../sensors/3" } // light
]
which means they are part of my sensor collection (which my weather station is).
To the user of my weather station, I would like to provide the meta information, that:
All three sensors are sensors (which implys the existence of certain properties)
Sensor 1 is a unidirectional sensor, whil 2 and 3 only measure for a specific direction
Sensor 3 provides addtional to the value (intensity) some spectral information.
So in Code:
class TemperatureSensor extends Sensor
class WindSensor extends Sensor implements DirectionalSensor
class LightSensor extends Sensor implements DirectionalSensor, SprectralSensor
How can I provide those information to the user, using Spring-HATEOAS or directly HAL?
I identified different methods to publish such information, with one being the content type of the resource and the other being a profile.
In general the media type defines how to process a payload but not necessarily what object or type its content relates to. I.e. on receiving a HTML payload you don't necessarily know that the page contains user information or the like, unless you have certain semantic annotations present within the markup. All HTML defines is a set of valid elements, how these elements have to be embedded in the payload (i.e. either <element>...</element> or <element/>), which attributes they support and when it is admissible to add which elements, i.e. certain elements such as the list-item tag <li> makes only sense as part of an unordered list <ul> or its counter-part the order list <ol>.
In regards to profiles, according to RFC 6906
A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms.
It is therefore a configuration option to set on the media-type processor, which depending on the profile specified, might apply additional validation rules, allow certain elements to appear in certain elements or the like. I.e. HTML4.01 added profiles to the <head> element so that search engines that understand this profile know that meta-information for author, date, keyword and copyright will be present which they can use directly instead of attempting to parse that information from the body directly.
HAL supports both the specification of profiles on media-type definitions as well as on link objects.
... how to provide sufficient meta information of what we are going to find in a resource after following a link.
In HTML a user is usually hinted what invoking a link might return by adding additional text, that summarizes the content of that target, or images, that express an affordance to the user, to the link context. For humans this is usually easy to understand though for an automated process such meta information are usually difficult to process and act upon. Instead of using free-text or images to express the relation the target has to the current content, link relations are used to express this.
According to RFC 8288 (Web Linking)
... an application will define the link relation type(s) it uses, along with the serialisation(s) that they might occur within. For example, the application "Web browsing" looks for the "stylesheet" link relation type in the HTML link serialisation (and optionally in the Link header field), whereas the application "AtomPub" uses the "edit" and "edit-media" link relations in the Atom serialisation.
Web linking also describes that link-relations not only describe simple semantics but also particular attributes or behaviors. More formally, they describe how the current context is related to an other resource.
Wikipedia describes link relations as:
A link relation is a descriptive attribute attached to a hyperlink in order to define the type of the link, or the relationship between the source and destination resources. The attribute can be used by automated systems, or can be presented to a user in a different way.
Such link relations should be based on standardized terms or make use of an extension mechanism, i.e. dublin-core. Microformats also lists plenty of commonly used relation names in HTML5. While link-relations must not constrain the processing of the current document or the availability of target representation types, they can specify certain behaviors or properties of target resources, i.e. that a resource supports certain HTTP methods or that support of certain media-type formats is required.
A link may have multiple different link relation names assigned. Clients that do not understand a certain link relation name should ignore it and only operate on those they do know and support. This basically just allows to add as many relation names to the URI context as needed. This is similar to the semantic Web where there may exist multiple predicates between a subject and object and further relation exist that indicate that a predicate expresses the same as an other one and may thus be used interchangingly.
HAL supports link-relations out of the box and adds CURIEs on top, which is a further reserved link-relation name itself, that hints a client on the location of a resource documentation. Link relation extension, as defined by RFC 8288, do not necessarily need to point to a documentation describing the semantics, therefore clients shouldn't access such URIs by default.
A links-section within a HAL representation response may look like this for the given problem statement:
...
"links": {
"self": { "href": "/weatherstation" },
"curies": [{ "name": "ws", "href": "http://api.weatherstation.com/docs/rels/{rel}", "templated": true }],
"ws:sensors": [
{ "href": "../sensors/1", "title": "temperature" },
{ "href": "../sensors/2", "title": "wind" },
{ "href": "../sensors/3", "title": "light" }
],
"ws:unidirectional": { "href": "../sensors/1", "title": "temperature" },
"ws:directional": [
{ "href": "../sensors/2", "title": "wind" },
{ "href": "../sensors/3", "title": "light" }
],
"ws:spectral": { "href": "../sensors/3", "title": "light" },
...
"http://api.weatherstation.com/rel/sensors": [
{ "href": "../sensors/1" },
{ "href": "../sensors/2" },
{ "href": "../sensors/3" }
],
"http://api.weatherstation.com/rel/unidirectional": { "href": "../sensors/1" },
"http://api.weatherstation.com/rel/directional": [
{ "href": "../sensors/2" },
{ "href": "../sensors/3" }
],
"http://api.weatherstation.com/rel/spectral": { "href": "../sensors/3" }
}
At this point I'm not 100% sure whether Curies also express link-relations or just express the documentation of a resource, hence I divided the sample above a bit. In theory they should be able to be valid link-relation names itself, in which case the latter definition may be skipped, as the HAL processor will resolve them to a full URI as required by RFC 8288 anyway.
While Web linking would allow for a link-relation such as:
Link: <../sensors/3>; rel="http://api.weatherstation.com/rel/sensors http://api.weatherstation.com/rel/directional http://api.weatherstation.com/rel/spectral"
that defines all 3 attributes on the same URI, I'm not sure if this is also possible in HAL directly.
Support for Curies is documented in the reference documentation where you basically just have to add a CurieProvider bean to your config. This Curie provider kicks in on all non registered link relations you define via RelProvider. Registered link relations can easily be added via new Link("/some-target", IanaLinkRelations.NEXT) for example as documented here
I've browsed the web for quite some time now, and have a good grasp on how Schema.org works. Now, it comes to mind that one could use Schema.org to let search engines know that this or that website is using particular software on the website, given that some functionality is provided to it. On the other hand, I can't find any references of major players doing so (WordPress, WooCommerce, Magento), so I was wondering:
How would I mark my piece of software, using Schema.org, on customer's website?
What exactly can I add as info to it (name, author, URLs, desc)?
Which types/properties should be used?
To add to point question 3, SoftwareApplication seems pretty much like something that would cover it. In Schema.org’s own examples, like following:
{
"#context": "http://schema.org",
"#type": "Restaurant",
"name": "Tartine Bakery",
"potentialAction": {
"#type": "ViewAction",
"target": [
"http://www.urbanspoon.com/r/6/92204",
{
"#type": "EntryPoint",
"urlTemplate": "http://api.urbanspoon.com/r/6/92204",
"contentType": "application/json+ld"
},
"android-app://com.urbanspoon/http/www.urbanspoon.com/r/6/92204",
{
"#type": "EntryPoint",
"urlTemplate": "urbanspoon://r/6/92204",
"actionApplication": {
"#type": "SoftwareApplication",
"#id": "284708449",
"name": "Urbanspoon iPhone & iPad App",
"operatingSystem": "iOS"
}
},
{
"#type": "EntryPoint",
"urlTemplate": "urbanspoon://r/6/92204",
"actionApplication": {
"#type": "SoftwareApplication",
"#id": "5b23b738-bb64-4829-9296-5bcb59bb0d2d",
"name": "Windows Phone App",
"operatingSystem": "Windows Phone 8"
}
}
]
}
}
Schema.org is used to provide info about an restaurant (why not software?). So, if anyone has an idea of how can this be done, it would be much appreciated.
Schema.org doesn’t offer a property to specify the SoftwareApplication that was used for generating a WebSite/WebPage.
The isBasedOn property might be used, given its broad definition ("A resource that was used in the creation of this resource."), but I guess it was not intended for this purpose.
Instead of specifying the software that is used for generating the pages (which is typically not interesting for consumers, especially since it doesn’t necessarily follow that certain features are available), it might make more sense to specify the potential actions offered by the site/pages:
RegisterAction
CommentAction
SearchAction
BuyAction
etc.
And from such an Action, you could use (where applicable) the target property to specify an EntryPoint which can specify with actionApplication which software is used to "complete the request".
(By the way, you can specify the software that was used to generate the HTML document as meta tag, no need for structured data: generator)
I'm trying to find the proper schema for telephones with extensions, but I can't find anything related to this problem through Google searches or schema.org.
In HTML, I'm using , to trigger the extension on cellphones and Skype, but I've also seen p used to "pause" between numbers when dialing. Which is the best route in regards to proper JSON-LD schema?
No extension used:
{
"#type": "Organization",
"telephone": "+18665554985"
}
Style 1 using p:
{
"#type": "Organization",
"telephone": "+18665554985p100"
}
Style 2 using ,:
{
"#type": "Organization",
"telephone": "+18665554985,100"
}
The telephone property has Text as expected value. If a specific format should be used, it would be noted in the property’s description, but that’s not the case for telephone.¹
So you can use whichever format you want.
Which format would make sense? I would go with the same format you display for your users (which would ideally be the recommended format according to a convention/standard relevant for the targeted users). This is the natural choice when using Microdata or RDFa to mark it up, and there is no reason to go a different route for JSON-LD. This would also help in cases where a consumer simply displays your value of the telephone property: it will be in the appropriate format for your users.
¹ There was some discussion about this in the issue Make the telephone property more structured (not just Text). I would expect that the expected range will, at some point, include URL values, so that tel URIs can be used (which of course have a specified format).
On forhand : sorry if I misunderstood hypermedia or Restfull concepts : it's a work in progress...)
I try to figure out hypermedia and hydra (http://www.markus-lanthaler.com/hydra), and have some questions about returning information to the client before designing my api.
say I have a webshop located at www.myshop.com
a HTTP GET to the root could return (for example) a list of resources represented as link (in a json-ld document):
...
"#id": "/api",
"products" : "www.myshop.com/api/products",
"customers":"www.myshop.com/api/customers"
...
First question on hydra, how could I add actions here ? it seems the client needs to load another document before the load of application. I mean the potential actions are not in the docuemnt retrieved from www.myshop.com/api Or do I miss something?
Then going further, I've stated that products is a hydra:Link so that the client could follow that link (interact with it) with a HTTP GET and retrieve a list of products. that will be a list like this :
....
{
"#id": "/api/products/123",
"#type": "vocab:Product"
},
{
"#id": "/api/products/124",
"#type": "vocab:Product"
},
....
here the client receives a list of product (That could be a paged collection). But if the client wants to display it to the user, let's say a table with [product Id, price, name] (not all Product's properties)
Second Question : How could I do that without the client sending a request to the server for each product, but still provide the link to get the product's detailed information,(or even here having four link : one for getting the detailed information, one for Delete and one for sharing it with a friend and a last one to add it to a Basket) ?
In fact I have difficulties to figure out how hydra is coming into play by not having Links in the document itself? I think that Hal uses this approach to having links in the document itself (if I am right) and I try to find how hydra does this link...
regards
A bit late but I'll nevertheless try to answer your questions Cedric.
say I have a webshop located at www.myshop.com
a HTTP GET to the root could return (for example) a list of resources
represented as link (in a json-ld document):
... "#id": "/api",
"products" : "www.myshop.com/api/products",
"customers":"www.myshop.com/api/customers" ...
First question on hydra, how could I add actions here ? it seems the
client needs to load another document before the load of application.
I mean the potential actions are not in the docuemnt retrieved from
www.myshop.com/api Or do I miss something?
You basically have two options here: 1) embed the operations directly in the response or 2) attach the operations to the properties (products, customers) instead.
Approach 1) would look somewhat like this:
...
"#id": "/api",
"products" : {
"#id": "http://www.myshop.com/api/products",
"operation": {
"#type": "Operation",
"method": "POST",
"expects": "Product"
}
}
...
While approach 2) would attach the same operation to the products property in the referenced Hydra ApiDocumentation:
...
"#id": "...products",
"supportedOperation": {
"#type": "Operation",
"method": "POST",
"expects": "Product"
}
...
Please note that in 1) I used operation while in 2) I used supportedOperation. Also, you should use a more specific type than Operation.
Regarding your second question:
with a HTTP GET and retrieve a list of products. that will be a list like this :
....
{
"#id": "/api/products/123",
"#type": "vocab:Product"
},
{
"#id": "/api/products/124",
"#type": "vocab:Product"
},
....
here the client receives a list of product (That could be a paged
collection). But if the client wants to display it to the user, let's
say a table with [product Id, price, name] (not all Product's
properties)
Second Question: How could I do that without the client sending a
request to the server for each product, but still provide the link to
get the product's detailed information,(or even here having four link
: one for getting the detailed information, one for Delete and one for
sharing it with a friend and a last one to add it to a Basket) ?
You can add as much information (including links) as you want directly in the collection.
....
{
"#id": "/api/products/123",
"#type": "vocab:Product",
"name": "Product 123",
"price": "9.99"
},
{
"#id": "/api/products/124",
"#type": "vocab:Product",
"name": "Product 124",
"price": "19.99"
},
....
That way, a client only needs to dereference an item if the collection doesn't contain that required information.
In fact I have difficulties to figure out how hydra is coming into
play by not having Links in the document itself?
Of course you do have links in the document as well. Links are just properties whose values happen to be URLs (objects with an #id property unless you set the property's type to #id in the context to get rid of that) instead of treating them specially.
note: The Hydra part of the answers I am not so sure, the JSON-LD and REST are okay I think.
You can use #base and relative IRIs by JSON-LD, or you can define namespaces in the #context, so after that you can use relative IRIs as ns:relativeIRI. Each one is better than returning the full IRI. (It is easier to parse the results with a general JSON-LD parser on client side, instead of a simple JSON parser.)
You can define your own #vocab using the Hydra vocab, or you can add "action" definitions in the #context. If you want to "add actions" you have to use hydra:Operation sub-classes in your vocab. Something like this (but I am not a Hydra expert):
{
"#id": "vocab:ProductList",
//...
"hydra:supportedOperations": [
{
"#type": "hydra:CreateResourceOperation",
"method": "POST",
"expects": "vocab:Product"
}
//...
]
}
In general by REST, if you need the same resource with fewer properties, then you have to add a new IRI for that resource, e.g.: /myresource?fewer=1. For example in your case: /api/products/?fields="id, price, name" is okay.
By Hydra you have 2 choices if you want multiple links; you can add a new hydra:Link as a property, or you can add a new hydra:Operation as a supportedOperation with method: GET. I guess get operations are for something like search which has an user input, but if you don't want to add a new property for each link, I think you have no other option.
Actually Hydra does have link and operation support. Maybe it is not clear, but JSON-LD is an RDF format, you can define RDF triples in that. So the IRIs you used for example by "customers":"www.myshop.com/api/customers" are just resource identifiers and not links. A link should have IRI, title, method(GET), language, content-type, iana:relation, etc... so it is not possible to describe a link you can follow with just a single IRI (resource identifier). By processing a REST resource a client should never check the IRI structure to know how to display what it got from you. You have to check the other properties of the links, especially iana:relations or by Hydra maybe operation type to do that. So for example in your case www.myshop.com/api/dav8ufg723udvbquacvd723fudvg is a perfectly valid IRI for the list of the customers. We use nice IRIs only because it is easier to configure generate them on server side, and configure a router for them.
Please check the Hydra vocab before further questions. As you can see a Class can have supportedOperations and supportedProperties which are both collections. A Link is a Property sub-class which can have a single Operation. By collections I think you have to use the Collection class, in which member contains the items of the collection... Be aware that by JSON-LD there is no difference by defining a single item or multiple items with the same type. In the context you have to define only the type, and the value of the property can contain both a single item or an array of items... If you want some constraints about that I guess you have to add some OWL triples, and a validator which checks the values using them.