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.

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.

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