Can anyone provide a good explanation of CURIEs and how to use them?

Question

I've seen CURIEs described in the HAL specification. At first glance, it looks like a way to provide templating for URIs. However, I also see it prominently mentioned that it can be used to access documentation on a rel. Which one is it? Is it simply a templating mechanism? Does anyone have an example for a good use case?

Also, would the following be a legal use of a CURIE? Or should it only be used to provide documentation on a rel?

    { 
        "id": 1,
        "name": "Social Media Bundle",
        "_links": {
            "self": {
                "href": "http://my.api.com/bundles/1"
            },
            "curies": {
                "name": "bundle",
                "href": "http://my.api.com/bundles/1{rel}"
                "templated": true
            },
            "bundle:channels": {
                "href": "/channels"
            }
        }
    }

Here bundle:channels would be expanded to http://my.api.com/bundles/1/channels.

Churlish

Just leaving a mention to myself for the next time that CURIE is short for Compact URI. – Monkhmer

Answer 1

According to page 7 of the HAL spec, curies are a suggested means by which to link documentation of a given resource:

Custom link relation types (Extension Relation Types in [RFC5988])
SHOULD be URIs that when dereferenced in a web browser provide
relevant documentation, in the form of an HTML page, about the
meaning and/or behaviour of the target Resource. This will improve
the discoverability of the API.

The CURIE Syntax [W3C.NOTE-curie-20101216] MAY be used for brevity for these URIs. CURIEs are established within a HAL document via a
set of Link Objects with the relation type "curies" on the root
Resource Object. These links contain a URI Template with the token
'rel', and are named via the "name" property.

{
  "_links": {
    "self": { "href": "/orders" },
    "curies": [{
      "name": "acme",
      "href": "http://docs.acme.com/relations/{rel}",
      "templated": true
    }],
    "acme:widgets": { "href": "/widgets" }
  }
}

The above demonstrates the relation "http://docs.acme.com/relations/ widgets" being abbreviated to "acme:widgets" via CURIE syntax.

The CURIE spec itself, has nothing specifically to do with documenting resources and is designed to enable compact URIs.

To answer your question, my interpretation of the specs would suggest that you have legitimately used the curie syntax but not in the context of HAL.

Candlefish

So it looks like they're not to be used for templating in general, which means that the example I've given in my question would be invalid according to the HAL specification, correct? That is, although what I have is a legitimate CURIE, it is not used legitimately in the context of HAL. – Churlish

they don't template the href of the link, they template the URL of the rel. with what you have bundle:channels would dereference to my.api.com/bundles/1channels [sic] to better illustrate since you've used the same character strings a lot...bundle:dog would dereference to my.api.com/bundles/1dog The href of either of those links is ONLY defined by the href field... in your example technically /channels would be ambiguous as HAL does not define the base URL for which relative URLs are calculated...but generally it'd be considered as my.api.com/channels – Andress

when we say "dereference", dereference by whom ? – Kudos

Answer 2

A CURIE is a replacement for a QName in non-XML languages which provides namespacing functionality for describing URL relations using shorthand based on prefix/suffix mappings in semantic data (RDFa, JSON-LD, YAML, etc.) without relying on XML namespaces.

The semantic web specifies this via Vocabulary Documents, in which a prefix is associated with a document, and a suffix is used to create an IRI based on this vocabulary. For example, the IRI http://xmlns.com/foaf/0.1/ specifies a Vocabulary Document, and name is a term in that vocabulary. Join the two items together and you have an unambiguous identifier for a vocabulary term. The Compact URI Expression, or short-form, is foaf:name and the expanded-form is http://xmlns.com/foaf/0.1/name. This vocabulary term identifies the given name for something, for example - a person's name.

For example:

If in RDF I want to use the Dublin Core creator property, then all I need do is this:

dc:creator

and provided that I have the dc namespace prefix defined as http://purl.org/dc/elements/1.1/, I have effectively represented the following URI:

http://purl.org/dc/elements/1.1/creator

In HTML it would look like this:

<div prefix="dc:http://purl.org/DC/elements/1.0"> 
 <a property="dc:creator" href="http://example.com">IANA</a>
</div>

References

• RDFa: Examples
• JSON-LD: Compact IRIs
• Compact URIs: CURIEs
• curie_map.yaml
• XML Glossary

Epithet