Brief Description

Describes an entity for a concept, with structure among concepts.

For a full description, visit the Service Description and Assumptions page.

Assumptions

Concepts can have a default generic use of concepts or terms (providing a flat namespace).
However, Concept is designed to allow multiple instances to provide more specific namespaces (e.g., material, technique, culture).
The initial version will allow for a single term per Concept record for version 2.3 of CollectionSpace. Refactoring of authorities to support preferred/non-preferred term will allow variants of terms to be supported.

For a complete list of assumptions, visit the Service Description and Assumptions page.

References

Vocabulary and Authority Overview
Concept Service Description and Assumptions

REST-based API

The Concept Service offers a REST-based Application Programming Interface (API) to CRUD (create, read, update, and delete) operations on individual ConceptAuthority instances, and on the associated Concept instances. These follow the Common model for CollectionSpace REST services.

Note that the Concept instances are not directly "addressable"; they can only be accessed via the parent ConceptAuthority.

ConceptAuthority CRUD+L services
ConceptAuthority REST payload schemas
Concept CRUD+L services
Concept REST payload schemas

ConceptAuthority CRUD+L services

Create a ConceptAuthority

Creates a new ConceptAuthority record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that ConceptAuthority record. Follows standard Create model. See the documentation of the ConceptAuthority schema, below. Example:

POST /cspace-services/conceptauthorities HTTP/1.1

Read a ConceptAuthority

Reads an existing ConceptAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the ConceptAuthority schema, below. Example:

GET /cspace-services/conceptauthorities/{id} HTTP/1.1

Update a ConceptAuthority

Updates an existing ConceptAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the ConceptAuthority schema, below. Example:

PUT /cspace-services/conceptauthorities/{id} HTTP/1.1

Delete a ConceptAuthority

Deletes an existing ConceptAuthority record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/conceptauthorities/{id} HTTP/1.1

List ConceptAuthority instances

Lists existing ConceptAuthority records, with summary information for each. Follows standard List model, with pagination support. See the documentation of the ConceptAuthority-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

pgSz for page size
pgNum for page size

Examples:

GET /cspace-services/conceptauthorities/ HTTP/1.1
GET /cspace-services/conceptauthorities/?pgSz=10 HTTP/1.1

ConceptAuthority REST payload schemas

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual ConceptAuthority records, please see the most recent ConceptAuthority schema.

ConceptAuthority instance schema

Create and Update should use the following schema. The value of vocabType must be "ConceptAuthority".

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document name="conceptauthorities">
  <ns2:conceptauthorities_common xmlns:ns2="http://services.collectionspace.org/concept">
    <displayName>Materials Authority</displayName>
    <vocabType>ConceptAuthority</vocabType>
    ...
  </ns2:conceptauthorities_common>
</document>

Read will return the above, plus additional fields (uri and csid) for access:

<?xml version="1.0" encoding="UTF-8"?>
<document name="conceptauthorities">
  <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
    <uri>/conceptauthorities/afbb91ca-3988-4524-bada</uri>
    ...
  </ns2:collectionspace_core>
  <ns2:conceptauthorities_common xmlns:ns2="http://collectionspace.org/services/concept" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    ...
    <csid>afbb91ca-3988-4524-bada</csid>
    ...
  </ns2:conceptauthorities_common>
</document>

ConceptAuthority-List schema

List (and variants) will return the following schema:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:abstract-common-list xmlns:ns2="http://collectionspace.org/services/jaxb">
  <pageNum>0</pageNum>
  <pageSize>40</pageSize>
  <itemsInPage>3</itemsInPage>
  <totalItems>3</totalItems>
  <fieldsReturned>csid|uri|updatedAt|displayName|refName|shortIdentifier|vocabType</fieldsReturned>
  <list-item>
    <csid>afbb91ca-3988-4524-bada</csid>
    <uri>/conceptauthorities/afbb91ca-3988-4524-bada</uri>
    <updatedAt>2012-03-29T00:51:04Z</updatedAt>
    <displayName>Materials Authority</displayName>
    <refName>urn:cspace:core.collectionspace.org:conceptauthorities:name(materials)'Materials Authority'</refName>
    <shortIdentifier>materials</shortIdentifier>
    <vocabType>ConceptAuthority</vocabType>
  </list-item>
  ...
</ns2:abstract-common-list>

Concept CRUD+L services

Concept instances are only accessible via the owning ConceptAuthority. The sub-resource is accessed with "items" (for consistency across all vocabulary-like services). In the examples below, the {concept-auth-id} parameter represents the CSID value of an existing ConceptAuthority instance.

Create a Concept in a ConceptAuthority

Creates a new Concept record. Assigns a unique, service-specified CollectionSpace ID (CSID) to that Concept record. Follows standard Create model. Must See the documentation of the Concept schema, below. Example:

POST /cspace-services/conceptauthorities/{concept-auth-id}/items HTTP/1.1

You may also POST a part called

<ns3:relations-common-list>

and any new relations there will be created. For example, this POST will add a relationship. Note that you must know beforehand the CSIDs of related terms. These are the CSIDs of two other Concept records, which must exist before this call. The special variable ${itemCSID} will be expanded to the CSID of the newly created Concept. (For Java use, please use the constant in CommonAPI.AuthorityItemCSID_REPLACE)

<?xml version="1.0" encoding="UTF-8"?>
<document name="concepts">
  <ns2:concepts_common xmlns:ns2="http://collectionspace.org/services/concept" xmlns:ns3="http://collectionspace.org/services/jaxb">
    <inAuthority>6ca3db57-7c96-47b6-b17d</inAuthority>
    <shortIdentifier>copper</shortIdentifier>
    <refName>urn:cspace:core.collectionspace.org:conceptauthorities:name(materials):item:name(copper)'Copper'</refName>
    <displayName>Copper</displayName>
    ...
  </ns2:concepts_common>
 
  <ns3:relations-common-list xmlns:ns3="http://collectionspace.org/services/relation" xmlns:ns2="http://collectionspace.org/services/jaxb">
    <relation-list-item>
      <predicate>hasBroader</predicate>
      <subject>
        <csid>${itemCSID}</csid>
        <documentType>Conceptitem</documentType>
      </subject>
      <object>
        <csid>a6d62e30-2bd6-439b-b19f</csid>
        <uri>/cspace-services/conceptauthorities/urn:cspace:name(concept)/items/a6d62e30-2bd6-439b-b19f</uri>
        <documentType>Conceptitem</documentType>
      </object>
    </relation-list-item>
    <relation-list-item>
      <predicate>hasBroader</predicate>
      <subject>
        <csid>0f33de2c-3dd5-4e5b-b6b6</csid>
        <uri>/cspace-services/conceptauthorities/urn:cspace:name(concept)/items/0f33de2c-3dd5-4e5b-b6b6</uri>
        <documentType>Conceptitem</documentType>
      </subject>
      <object>
        <csid>${itemCSID}</csid>
        <documentType>Conceptitem</documentType>
      </object>
    </relation-list-item>
    <relation-list-item>
      <predicate>hasBroader</predicate>
      <subject>
        <uri>/cspace-services/conceptauthorities/urn:cspace:name(concept)/items/b439ca2f-448c-4251-a2d9</uri>
        <csid>b439ca2f-448c-4251-a2d9</csid>
        <documentType>Conceptitem</documentType>
      </subject>
      <object>
        <csid>${itemCSID}</csid>
        <documentType>Conceptitem</documentType>
      </object>
    </relation-list-item>
    <relation-list-item>
      <predicate>hasBroader</predicate>
      <subject>
        <uri>/cspace-services/conceptauthorities/urn:cspace:name(concept)/items/8c7853a1-f1d3-4ae5-8511</uri>
        <csid>8c7853a1-f1d3-4ae5-8511</csid>
        <documentType>Conceptitem</documentType>
      </subject>
      <object>
        <csid>${itemCSID}</csid>
        <documentType>Conceptitem</documentType>
      </object>
    </relation-list-item>
  </ns3:relations-common-list>
</document>

NOTE: if you wish to delete related items,
simply send relations-common-list as an empty element.
This is shown in a comment here:
http://wiki.collectionspace.org/display/collectionspace/Person+Service+REST+APIs?focusedCommentId=72220749&#comment-72220749

Read a Concept in a ConceptAuthority

Reads an existing Concept record, specified by its CollectionSpace ID (CSID). Follows standard Read model. See the documentation of the Concept schema, below. Example:

GET /cspace-services/conceptauthorities/{concept-auth-id}/items/{id} HTTP/1.1

There are additional query parameters to get the relations for this item.
Query Parameters are defined and explained here, with examples: Authority REST API for Hierarchies\

Update a Concept in a ConceptAuthority

Updates an existing Concept record, specified by its CollectionSpace ID (CSID). Follows standard Update model. See the documentation of the Concept schema, below. Example:

PUT /cspace-services/conceptauthorities/{concept-auth-id}/items/{id} HTTP/1.1

You may also PUT a part called

<ns3:relations-common-list>

and any new relations there will be created. Relations to the updated item which are missing from the relations list in the PUT will be deleted from persistence. No target records are deleted, just the relations records that point to target records. e.g. POST to authority with Concept "Drawing", with relations-common-list that has an entry for ${itemCSID} hasBroader "Art" creates a relations record that references both Art and Drawing. When a PUT is made that does not have the relation for Art, then Drawing has no relations, so the relations record for Drawing==>hasBroader==>Art is deleted, but both "Drawing" and "Art" Concept records remain.

Delete a Concept in a ConceptAuthority

Deletes an existing Concept record, specified by its CollectionSpace ID (CSID). Follows standard Delete model. Example:

DELETE /cspace-services/conceptauthorities/{concept-auth-id}/items/{id} HTTP/1.1

List Concept instances in a ConceptAuthority

Lists existing Concept records, with summary information for each. Follows standard List model. See the documentation of the Concept-List schema, below. List supports the following common parameters for List results, pagination controls and query filters:

pgSz for page size
pgNum for page size
pt for partial-term matching, to support term completion.

Examples:

GET /cspace-services/conceptauthorities/{concept-auth-id}/items/ HTTP/1.1
GET /cspace-services/conceptauthorities/{concept-auth-id}/items/?pt=foo&pgSz=10 HTTP/1.1

Concept REST payload schemas

The schemas below are abbreviated, and are thus illustrative. For a full list of the fields that may potentially be present in payloads when creating, updating, or reading individual Concept records, please see the most recent Concept schema (i.e. for an individual Concept term within a ConceptAuthority or vocabulary).

Concept instance schema

Create and Update should use the following schema.

On create, the value of inAuthority must match the identifier of the parent ConceptAuthority, and will not be modified once the instance is created.

You can view the full set of validation constraints on the data you submit when creating or updating Concept instance records, in the most recent CollectionSpace code, via this Java source code file.

Here's an example payload for creating a new instance:

<?xml version="1.0" encoding="UTF-8"?>
<document name="concepts">
  <ns2:concepts_common xmlns:ns2="http://collectionspace.org/services/concept" xmlns:ns3="http://collectionspace.org/services/jaxb">
    <inAuthority>6ca3db57-7c96-47b6-b17d</inAuthority>
    <shortIdentifier>copper</shortIdentifier>
    <refName>urn:cspace:core.collectionspace.org:conceptauthorities:name(materials):item:name(copper)'Copper'</refName>
    <displayName>Copper</displayName>
    <termLanguage>urn:cspace:core.collectionspace.org:vocabularies:name(languages):item:name(eng)'English'</termLanguage>
    ...
  </ns2:concepts_common>
</document>