That is (examples taken from the latest XLink 1.1 spec),
<go ... xlink:arcrole="http://www.example.com/linkprops/auditor" ...>
<my:crossReference ... xlink:role="http://www.example.com/linkprops/studentlist" ...>
what could the content of the http://www.example.com/linkprops/studentlist resource be?
Is it totally arbitrary, only constrained by the developer/platform/etc, or does it have to have a specific format (e.g., XML, conforming to a specific schema, etc.)?
Based on the quote below, I would say that it is arbitrary, but I couldn't find any examples yet:
Attribute title provides a human-readable description of the [extended] link, and attribute role provides a machine-readable description of the link.
Also, from XML in a Nutshell, 2nd Edition:
10.4.2.3. Arc roles:
[..] this URI should point to a resource that indicates which relationship the arc describes (e.g., parent-child, employer-employee). For instance, we might add an xlink:arcrole attribute to the purchase arc that pointed to the URL http://www.example.com/purchase_details.txt.
The file purchase_details.html might then contain the text "will be bought from." This would indicate that the source of the link is bought from the target of the link; that is, "The Wonderful Wizard of Oz will be bought from Amazon", or "The Wonderful Wizard of Oz will be bought from Fatbrain", or "The Wonderful Wizard of Oz will be bought from Barnes & Noble". However, although this usage is suggested, XLink processors will not enforce it, and indeed there's really no way they could be asked to do this since that would require that they actually understand what they read.
the xlink:role attribute contains an absolute URI that somehow describes or annotates the remote resource
Although can't fathom how the example links, such as http://www.williammorrow.com, are useful as roles at all.
Some mentions from the spec:
the role attribute indicates a property that the entire link has
Section 5.5 Semantic Attributes (role, arcrole, and title) states that "The value of the role or arcrole attribute is a [Legacy extended IRIs]. The identifier must not be relative."
Section 5.1.3 Traversal Rules for an Extended Link (arc-Type Element) brings a specific example that "a resource might generically represent a "person," but in the context of a particular arc it might have the role of "mother" and in the context of a different arc it might have the role of "daughter"." But how does these translate to an URI?
(It also doesn't help that the same section uses "roles" interchangeably with "labels"...)
Some other sites I've found:
Peter Egri: Overview on XLink
No examples, but it is good summary.
http://www.brenkoweb.com/tutorials/xml/xml-xlink-xml-linking/xlink-attributes
https://www.brainbell.com/tutorials/XML/Linking_With_XLink.htm
Both of these provide examples to role with simple strings (e.g., "employee") so they are not normative.
Found the answer in the 3rd edition of XML in a Nutshell, Link Semantics chapter:
The xlink:role attribute contains a URI that somehow indicates the meaning of the link. For instance, the URI http://www.isi.edu/in-notes/iana/assignments/media-types/text/css might be understood to mean that the link points to a CSS stylesheet for the document in which the link is found. However, there are no standards for the meanings of role URIs. Applications are free to assign their own meaning to their own URIs.
For example, this book element is a simple XLink that points to Scott’s author page at O’Reilly. The xlink:title attribute contains his name, while the xlink:role attribute points contains the URI for the Dublin Core creator property, thereby indicating he’s an author of this book.
<book xlink:type="simple"
xlink:href="http://www.oreillynet.com/cs/catalog/view/au/751"
xlink:title="W. Scott Means"
xlink:role="http://purl.org/dc/elements/1.1/creator" >
XML in a Nutshell
</book>
Related
I have found several official AWS documents that describe some of the structure/schema for specifying models in Yaml files. For example:
https://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html
https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html#sam-resource-api--examples--simpleapiexample--yaml
In particular, the first document says this at the end:
The examples don't use advanced JSON schema features, such as specifying required items, minimums and maximums (for allowed string lengths, numeric values, and array item lengths), and regular expressions. For more information, see Introducing JSON and JSON schema draft 4.
and links out to https://www.json.org/json-en.html and https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04
Neither of those documents describe anything about required items, minimums and maximums, or any of these other "advanced" JSON schema features.
Is there some canonical reference that shows what is possible when describing models in a yaml file, and what the syntax is? How does anyone know what to type? For example, when writing a model, how does anyone know that:
MyModel:
description: this is an object with one property
type: object
properties:
grade:
type: integer
is correct. while:
MyModel:
description: this is an object with one property
type: object
properties:
grade:
type: int
is not correct?
The AWS page is indeed a bit poorly worded. "JSON Schema" is the name of a set of specifications, and "Draft 4" is a particular version of those specifications. (The name "draft" is something of a misnomer, which exists for historic and bureaucratic reasons, so you can read that as "Version 4" or "Release 4".)
The home page for JSON Schema is at https://json-schema.org where you can find the current version of the base specification (which just describes the general format) and the validation specification, which is what you were looking for.
For older versions, you need to look at https://json-schema.org/specification-links.html so if the AWS documentation is correct that API Gateway only supports Draft 4 (from about 10 years ago), the more useful page to link to would have been this: https://datatracker.ietf.org/doc/html/draft-fge-json-schema-validation-00
I've seen URIs that support magic ids for the authenticated user like below:
GET /user/me - list my profile
GET /user/me/photos - list my photos
where the ones below use the actual user id
GET /user/742924
GET /user/742924/photos
The problem I see is that the same resource id points to a different resource depending on the authenticated user.
Is this going against any REST principles?
Using /me to name a resource that corresponds to the authenticated user is perfectly fine from a REST perspective. According to Roy Thomas Fielding's dissertation, any information that can be named can be a resource:
5.2.1.1 Resources and Resource Identifiers
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. [...]
When using /me, you have a locator for the authenticated user and it will always identify the concept of an authenticated user, regardless of which user is authenticated.
While I agree with Cassio, I think he didn't select the best quote from the dissertation, since this is a part that's a lot more identifier specific:
The definition of resource in REST is based on a simple premise: identifiers should change as infrequently as possible. Because the Web uses embedded identifiers rather than link servers, authors need an identifier that closely matches the semantics they intend by a hypermedia reference, allowing the reference to remain static even though the result of accessing that reference may change over time. REST accomplishes this by defining a resource to be the semantics of what the author intends to identify, rather than the value corresponding to those semantics at the time the reference is created. It is then left to the author to ensure that the identifier chosen for a reference does indeed identify the intended semantics.
And if you connect the dots, a logged in user is the case in point - same reference to a different resulting content.
That is perfectly fine.
Whether it is the same entity in the database is irrelevant, the more correct description would be that every concept needs to have a URI. The concept of "current user" is different from "user 742924", so it is ok.
It can be even worse than that, "current user", "last logged in user", "user with name starting with A", "oldest user", etc. All of those can be different resources, even though they may point to the same "user".
In a RESTful service, you can define links to resources as so:
<next xmlns="http://example.org/state-machine"
rel="http://mydomain.example.org/user"
url="http://mydomain.example.com/user/1234"
type="application/xml"/>
Or a JSON-LD Example:
{
"#context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"#id": "http://xmlns.com/foaf/0.1/homepage",
"#type": "#id"
}
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
}
Or a vCard example:
<address id="hcard" class="vcard">
<p class="fn n">
<span class="given-name">First</span>
<span class="additional-name">M</span>.
<span class="family-name">Last</span>
With the rel attribute pointing to a schema/microformat/microdata/RDFa description of that free-offer object within the domain. Say I have a user object with fields name and homepage,
In the examples above, would rel="http://mydomain.example.org/user" be more appropriate since it is domain specific user or should I use something like this from foaf?
"name": "http://xmlns.com/foaf/0.1/name",#id": http://xmlns.com/foaf/0.1/homepage"
I am very confused with these RDFa, microformat, microdata, schema, vcards, hcards, foaf, http://www.productontology.org/id/, www.schema.org/name, http://rdf.data-vocabulary.org/#name, json schema, etc. When do I create my own microformat/schema, and when do I use the public ones defined in those different areas (vCards, hcards, foaf, productontology, schema.org)? I understand that RDFa, microformats, etc., are really public metadata about data, but where can I find a full list of them to use?
If I were to create my own rel like rel="http://mydomain.example.org/user", defining the user object, how should I document it? Is there a standard I can follow? Some places suggest human readable discovery documents, or maybe a JSON/XML schema at that location describing the contract and the version?
One suggestion is to have a different version of http://mydomain.example.com/v1/user/1234 to talk to with a different version of specification for the service so existing client won't break on version change.
Please help me map out this confusion, or the terms I should use, with regards to Microformat, RDF, Microdata, Schema, etc.
When just started learning RDF/Ontology, I’ve the same confusion.
There are a lot of vocabs from many different organizations. The key is to use the ones that are well established and adopted by others; but also more importantly, make sure that to use the ‘terms’ which represent the ‘semantic meanings’ that you intend to mean.
To answer your specifics questions:
1) You ‘can’ create your own terms but the point is that when other applications parse your terms, the application will need to know what your terms really means. If you use FOAF:homepage, all applications know its semantic meaning and what it refers to and also from that, it implies that whoever is the subject (subject in the rdf tripple) of FOAF:homepage is a FOAF:Person. There is where open linked data comes in.
http://linkeddata.org/
2) Myself does not have a lot of experience with RDFa/Microfromat, my understanding is that these technologies want to provide machine understandable semantic terms at the HTML layer. I think you may not want to create your own if there are existing ones but you can have your own terms defined in addition to what is out there.
3) You can define terms using OWL or RDFS
Just saw this, it may be useful..
https://code.google.com/p/tdwg-rdf/wiki/Beginners7OWL
But in my light way project, we just create terms by specifying the namespace, name of the term and what it mean.. You can follow the following to define your terms:
http://dublincore.org/documents/dcmi-terms/
JSON/XML/N3… are just different serialization formats and the same term can be serialized using many different formats. The important thing to remember is that you define the semantic meaning of the terms and they will be serialized to different formats. It is not that the format is not important but all formats point to the same term and same meaning.
4) Myself version my vocabs.. But I don’t have much insights into the best practices.
Hope this help!!
There is a well known expression of this in RDFa:
<html><body vocab="http://purl.org/dc/terms/">
<div typeof="foaf:Person">
<span property="creator">manu sporny</span>
<span property="foaf:age" content="66"/>
<span property="foaf:homepage" resource="http://x.com"/>
</div>
</body></html>
The "foaf" prefix is defaulted by RDFa. No context to define.
The "dc" prefix is made the default, no prefix required for "creator".
This is the standard, forget everything else.
The list of directly usable prefixes is provided by
http://www.w3.org/2011/rdfa-context/rdfa-1.1
You may find here a lot of usable concepts, in fact all the public schemas.
Note the "schema" prefix, for a vocabulary defined here:
http://schema.org/
It is specially rich, and widely used.
Note also that it tried to define a microformat to compete with RDFa notation. Drop that and use the vocabulary with RDFa.
I have a Sitecore layout that generates a vCard from a Sitecore item, including a person's name, business address, etc, and saves it as a file on the web server for later (fast) retrieval. Part of the vCard is the organization (business) name. We're an international firm, which means that across the different locales our firm name is slightly different.
For example, in English our name is [Firm Name] LLP, while in Swedish it is [Firm Name] Advokat AB.
The language context used when generating vCards is English, but the org name is localized within Sitecore. Is it possible to switch from English to another language context to grab the localized org name, and then switch back?
Alternative Approach
The alternative I'm pondering would be to just hard-code the org name in the code, and based on the person's office address output the correct org name. The downside of this would be that I wouldn't be taking advantage of Sitecore's localization capabilities. In addition, there may be other components of the vCard that will eventually be localized - I don't want to hard-code everything.
Is this to any help?
Language theLanguage = Sitecore.Globalization.Language.Parse("sv-SE");
Item theOriginalItem = Sitecore.Context.Database.GetItem("/sitecore/content/home/theitem");
Item theLanguageSpecificItem = Sitecore.Context.Database.GetItem(theOriginalItem.ID, theLanguage);
Coming from a lot of frustrating times with WSDL/Soap, I very much like the REST paradigm, but am trying to solve two basic problems in our application, before moving over to REST. The first problem relates to the lack of an interface document. I think I finally see how to handle this situation: One can query his way down from a top-level "/resources" resource using various requests of GET, HEAD, and OPTIONS to find the one needed resource in the correct hypermedia format. Is this the idea? If so, the client need only be provided with a top-level resource URI: http://www.mywebservicesite.com/mywebservice/resources. He will then have to do some searching and possible keep track of what he is discovering, so that he can use the URIs again efficiently in future to do GETs, POSTs, PUTs, and DELETEs. Are there any thoughts on what should happen here?
The other problem is that we cannot use descriptive URLs like /resources/../customer/Madonna/phonenumber. We do have an implementation of opaque URLs we use in the context of a session, and I'm wondering how opaque URLs might be applied to REST. The general problem is how to keep domain-specific details out of URLs, and still benefit from what REST has to offer.
The other problem is that we cannot use descriptive URLs like /resources/../customer/Madonna/phonenumber.
I think you've misunderstood the point of opaque URIs. The notion of opaque URIs is with respect to clients: A client shall not decipher a URI to guess anything of semantic meaning from it. So a service may well have URIs like /resources/.../customer/Madonna/phonenumber, and that's quite a good idea. The URIs should be treated as opaque by clients: not infer from the URI that it represents Madonna's phone number, and that Madonna is a customer of some sort. That knowledge can only be obtained by looking inside the URI itself, or perhaps by remembering where the URI was discovered.
Edit:
A consequence of this is that navigation should happen by links, not by deconstructing the URI. So if you see /resouces/customer/Madonna/phonenumber (and it actually represents Customer Madonna's phone number) you should have links in that resource to point to the Madonna resource: e.g.
{
"phone_number" : "01-234-56",
"customer_URI": "/resources/customer/Madonna"
}
That's the only way to navigate from a phone number resource to a customer resource. An important aspect is that the server implementation might or might not have domain specific information in the URI, The Madonna record might just as well live somewhere else: /resources/customers/byid/81496237. This is why clients should treat URIs as opaque.
Edit 2:
Another question you have (in the comments) is then how a client, with the required no knowledge of the server's URIs is supposed to be able to find anything. Clients have the following possibilities to find resources:
Provide a search interface. This could be done by providing an OpenSearch description document, which tells clients how to search for items. An OpenSearch template can include several variables, and several endpoints, depending on what you're looking for. So if you have a "customer ID" that's unique, you could have the following template: /customers/byid/{proprietary:customerid}", the customerid element needs to be documented somewhere, inside the proprietary namespace. A client can then know how to use such a template.
Provide a custom form. This implies making a custom media type in which you explicitly define how (based on an instance of the document) a URI to a customer can be forged. <customers template="/customers/byid/{id}"/>. The documentation (for the media type) would have to state that the template attribute must be interpreted as a relative URI after the string substitution "{id}" to an actual customer ID.
Provide links to all resources. Some resources aren't innumerable, so you can simply make a link to each and every one of them, optionally including identifying information along with the links. This could also be done in a custom media type: <customer id="12345" href="/customer/byid/12345"/>.
It should be noted that #1 and #2 are two ways of saying the same thing: Clients are allowed to create URIs if they
haven't got the URI structure a priori
a media type exists for which the documentation states that URIs should be created
This is much the same way as a web browser has no idea of any URI structure on the web, except for the rules laid out in the definition of HTML forms, to add a ? and then all the query parameters separated by &.
In theory, if you have a customer with id 12345, then you could actually dispense with the href, since you could plug the customer id 12345 into #1 or #2. It's more common to actually provide real links between resources, rather than always relying on lookup or search techniques.
I haven't really used web RPC systems (WSDL/Soap), but i think the 'interface document' is there mostly to allow client libraries to create the service API, right? if so, REST shouldn't need it, because the verbs are already defined and don't really need to be documented again.
AFAIUI, the REST way is to document the structure of each resource (usually encoded in XML or JSON). In that document, you'll also have to document the relationship between those resources. In my case, a resource is often a container of other resources (sometimes more than one type), therefore the structure doc specifies what field holds a list of URLs pointing to the contained resources. Ideally, only one unique resource will need a single, fixed (documented) URL. everithing else follows from there.
The URL 'style' is meaningless to the client, since it shouldn't 'construct' an URL. Every URL it needs should be already constructed on a resource field. That let's you change the URL structure without changing the client (that has saved tons of time to me). Your URLs can be as opaque or as descriptive as you like. (personally, i don't like text keys or slugs; my keys are all BIGINTs or UUIDs)
I am currently building a REST "agent" that addresses the first part of your question. The agent offers a temporary bookmarking service. The client code that is interacting with the agent can request that an URL be bookmarked using some identifier. If the client code needs to retrieve that representation again, it simply asks the agent for the url that corresponds to the saved bookmark and then navigates to that bookmark. Currently those bookmarks are not persisted so they only last for the lifetime of the client application, but I have found it a useful mechanism for accessing commonly used resources. E.g. The root representation provides a login link. I bookmark that link and if the client ever receives a 401 then I can redirect to the "login" bookmark.
To address an issue you mentioned in a comment, the agent also has the ability to store retrieved representations in a dictionary. If it becomes necessary to aggregate and manipulate multiple representations at the same time then I can simply request that the agent store the current representation in a dictionary associated to a key and then continue navigating to the next resource. Once the client has accumulated all the necessary representation it can do what it needs to do.