List of UMBEL Web Services    Invoke this Web Service    Short Description of this Web Service Access this Web Service
 
API and Documentation

Reporter: Subject Concepts Web Service API Documentation






For background, we suggest first reading the about section for this Web Service. Also, you may want to consult this document for an overall discussion of API design and philosophy.

Developers communicate with the Reporter: Subject Concept Structured Dynamics LLC. UMBEL Web service using the HTTP GET method. You may request one of the following mime types: (1) text/xml, (2) application/rdf+xml and (3) application/rdf+n3. The content returned by the Web service will be serialized using the mime type requested and the data returned will depend on the parameters selected.

Web Service Endpoint Information

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline UMBEL Web services may not offer other values than the default.

HTTP Method:
  • GET

Possible "Accept:" HTTP header field value:
URI:
  • http://umbel.structureddynamics.com/ws/reporter/subject_concept/
    ?mode=param1&source_subject_concept=param2&lang=param3


URI dynamic parameters description:

Note: All parameters have to be URL-encoded
  • param1. One or more of:
    Note: if more than one parameter is added,
    the list is separated by a semicolon ";"
    • " definition (default)": Include the definition of the
      subject concept
    • " pref_label (default)": Include the preferred label
      of the subject concept
    • " alt_label (default)": Include the alternative
      label(s) of the subject concept
    • " parent_concept ": Include the parent concepts of
      the subject concept
    • " child_concept ": Include the child concepts of
      the subject concept
    • " equivalent_other_class ": Include the external
      classes equivalent to the subject concept
    • " narrower_other_class ": Include external classes
      sub-class-of the subject concept
    • " broader_other_class ": Include external classes
      super-class-of the subject concept
    • " in_domain_of ": Include predicates where the
      subject concept can be object
    • " in_range_of ": Include predicates where the
      subject concept can be a subject
  • param2. The URI of a UMBEL subject concept
  • param3. One of:
    • " en (default)": Labels of resultsets in English if available

Example of Returned XML Document

This is an example of the XML document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL subject concept.


Query:
  • http://umbel.structureddynamics.com/ws/reporter/subject_concept/
    ?description=definition;pref_label;alt_label
    &source_subject_concept=http://umbel.org/umbel/sc/Person
"Accept:" HTTP header field value::
  • text/xml

Result:
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!DOCTYPE resultset PUBLIC
    "-//Structured Dynamics LLC. LLC.//Infer Validator DTD 0.1//EN"
    "http://umbel.structureddynamics.com/ws/dtd/reporter/subject_concept.dtd">
  3. <resultset>
  4.   <subject type="umbel:SubjectConcept"
    uri="http://umbel.org/umbel/sc/Person">
  5.     <relation type="skos:definition">
  6.       <object type="rdfs:Literal">A specialization of SocialBeing
    and IndividualAgent: the collection of all persons. Personhood
    is a vague, emotionally loaded yet extremely salient concept
    with respect to common-sense reasoning. Something is an
    instance of Person if it is an individual IntelligentAgent with
    perceptual sensibility, capable of complex social relationships,
    and possessing a certain moral sophistication and an intrinsic
    moral value, or -- if it lacks certain of these characteristics --
    is a member of a distinct type of SocialBeing (usually a species)
    which generally possesses such characteristics and is therefore
    acknowledged by other members of that type as a person within
    their social systems. Most currently known instances of Person
    are instances of HomoSapiens but there is no reason why all
    need be (consider Hobbits in the fictional world of
    LordOfTheRings_Trilogy). They need not even be instances of
    BiologicalLivingObject (consider the possibility of a person-like
    AI). Also note that Person excludes non-human "legal persons",
    who are, however, included in the collection LegalAgent.</object>
  7.     </relation>
  8.     <relation type="skos:prefLabel">
  9.       <object type="rdfs:Literal">person</object>
  10.     </relation>
  11.     <relation type="skos:altLabel">
  12.       <object type="rdfs:Literal">human</object>
  13.       <object type="rdfs:Literal">layman</object>
  14.       <object type="rdfs:Literal">laymen</object>
  15.       <object type="rdfs:Literal">manpower</object>
  16.       <object type="rdfs:Literal">mortal</object>
  17.       <object type="rdfs:Literal">mortals</object>
  18.       <object type="rdfs:Literal">people</object>
  19.       <object type="rdfs:Literal">persons</object>
  20.     </relation>
  21.   </subject>
  22. </resultset>

DTD of the XML Document

  1. <!DOCTYPE resultset [
  2.  
  3.         <!ELEMENT resultset (subject) >
  4.        
  5.         <!ELEMENT subject (predicate)+>
  6.         <!ATTLIST subject type (umbel:SubjectConcept)
    "umbel:SubjectConcept">
  7.         <!ATTLIST subject uri CDATA #REQUIRED>
  8.  
  9.         <!ELEMENT predicate (object)+>
  10.         <!ATTLIST predicate type (skos:definition |
    skos:prefLabel | skos:altLabel | rdf:type |
    skos:broaderTransitive | skos:narrowerTransitive
    | owl:equivalentClass | rdfs:subClassOf
    | umbel:superClassOf | ws:in_domain_of |
    ws:in_range_of) "skos:definition">
  11.  
  12.         <!ELEMENT object (#PCDATA)*>
  13.         <!ATTLIST object type (owl:Class | umbel:SubjectConcept
    | rdfs:Literal | rdf:Property) "owl:Class">
  14.         <!ATTLIST object uri CDATA #REQUIRED>
  15.         <!ATTLIST object label CDATA #IMPLIED>
  16.  
  17. ]>

Descriptions of the Types of XML Elements

Here are descriptions of the types of XML elements that might be returned from from this Web service. Please read the XML data structure documentation to understand how the data is structured within these XML documents.

  • umbel:SubjectConcept (subject/object). An UMBEL subject concept
    resource returned by the Web service for the requested parameters
  • owl:Class (subject/object). A class defined in another
    vocabulary than UMBEL
  • rdfs:Literal (object). An object that defines a string literal.
  • rdf:Property (subject/object). A predicate
  • skos:definition (predicate). Defines the definition of a subject or
    an object
  • skos:prefLabel (predicate). Defines the preferred label to refers to a
    subject or an object
  • skos:altLabel (predicate). Defines the alternative label(s) to refers
    to a subject or an object
  • rdf:type (predicate). Defines the type(s) of a subject or an object
  • skos:broaderTransitive (predicate). Link a umbel:SubjectConcept to a
    more general umbel:SubjectConcept
  • skos:narrowerTransitive (predicate). Link a umbel:SubjectConcept to a
    more specific umbel:SubjectConcept
  • owl:equivalentClass (predicate). Link a umbel:SubjectConcept or a
    owl:Class to an equivalent owl:Class
  • rdfs:subClassOf (predicate). Link a umbel:SubjectConcept or a
    owl:Class to a sub-class-of a owl:Class
  • umbel:superClassOf (predicate). Link a umbel:SubjectConcept or a
    owl:Class ot a super-class-of a owl:Class
  • ws:in_domain_of (predicate). Link a umbel:SubjectConcept or a
    owl:Class to a rdf:Property where it can appears as an object
    of that predicate
  • ws:in_range_of (predicate). Link a umbel:SubjectConcept or a
    owl:Class to a rdf:Property where it can appears as a subject
    of that predicate

Example of Returned RDF/XML Document

Here is an example of a RDF/XML document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL subject concept.


Query:
  • http://umbel.structureddynamics.com/ws/reporter/subject_concept/
    ?description=definition;pref_label;alt_label
    &source_subject_concept=http://umbel.org/umbel/sc/Person
"Accept:" HTTP header field value:
  • application/rdf+xml

Result:
  1. <?xml version="1.0"?>
  2. <rdf:RDF xmlns:umbel="http://umbel.org/umbel#"
    xmlns:owl="http://www.w3.org/2002/07/owl#"
    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:skos="http://www.w3.org/2008/05/skos#"
    xmlns:ws="http://umbel.org/umbel/ws#">
  3.  
  4. <owl:Thing rdf:about="http://umbel.org/umbel/sc/Person">
  5.     <skos:definition>A specialization of SocialBeing and
    IndividualAgent: the collection of all persons. Personhood
    is a vague, emotionally loaded yet extremely salient concept with
    respect to common-sense reasoning. Something is an instance of
    Person if it is an individual IntelligentAgent with perceptual sensibility,
    capable of complex social relationships, and possessing a certain moral
    sophistication and an intrinsic moral value, or -- if it lacks certain of
    these characteristics -- is a member of a distinct type of SocialBeing
    (usually a species) which generally possesses such characteristics and
    is therefore acknowledged by other members of that type as a person
    within their social systems. Most currently known instances of Person
    are instances of HomoSapiens but there is no reason why all need be
    (consider Hobbits in the fictional world of LordOfTheRings_Trilogy).
    They need not even be instances of BiologicalLivingObject (consider
    the possibility of a person-like AI). Also note that Person excludes
    non-human "legal persons", who are, however, included in the
    collection LegalAgent.</skos:definition>
  6.     <skos:prefLabel>person</skos:prefLabel>
  7.     <skos:altLabel>human</skos:altLabel>
  8.     <skos:altLabel>layman</skos:altLabel>
  9.     <skos:altLabel>laymen</skos:altLabel>
  10.     <skos:altLabel>manpower</skos:altLabel>
  11.     <skos:altLabel>mortal</skos:altLabel>
  12.     <skos:altLabel>mortals</skos:altLabel>
  13.     <skos:altLabel>people</skos:altLabel>
  14.     <skos:altLabel>persons</skos:altLabel>
  15. </owl:Thing>

Example of Returned RDF/N3 Document

Here is an example of a RDF/N3 document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL subject concept.


Query:
  • http://umbel.structureddynamics.com/ws/reporter/subject_concept/
    ?description=definition;pref_label;alt_label
    &source_subject_concept=http://umbel.org/umbel/sc/Person
"Accept:" HTTP header field value:
  • application/rdf+n3

Result:
  1. @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
  2. @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
  3. @prefix owl: <http://www.w3.org/2002/07/owl#> .
  4. @prefix umbel: <http://umbel.org/umbel#> .
  5. @prefix skos: <http://www.w3.org/2008/05/skos#> .
  6. @prefix ws: <http://umbel.org/umbel/ws#> .
  7. <http://umbel.org/umbel/sc/Person> a owl:Thing ;
  8.     skos:definition """A specialization of SocialBeing and
    IndividualAgent: the collection of all persons. Personhood
    is a vague, emotionally loaded yet extremely salient concept
    with respect to common-sense reasoning. Something is an
    instance of Person if it is an individual IntelligentAgent with
    perceptual sensibility, capable of complex social relationships,
    and possessing a certain moral sophistication and an intrinsic
    moral value, or -- if it lacks certain of these characteristics --
    is a member of a distinct type of SocialBeing (usually a species)
    which generally possesses such characteristics and is therefore
    acknowledged by other members of that type as a person
    within their social systems. Most currently known instances of
    Person are instances of HomoSapiens but there is no reason
    why all need be (consider Hobbits in the fictional world of
    LordOfTheRings_Trilogy). They need not even be instances
    of BiologicalLivingObject (consider the possibility of a person-like
    AI). Also note that Person excludes non-human "legal persons",
    who are, however, included in the collection LegalAgent.""" ;
  9.     skos:prefLabel """person""" ;
  10.     skos:altLabel """human""" ;
  11.     skos:altLabel """layman""" ;
  12.     skos:altLabel """laymen""" ;
  13.     skos:altLabel """manpower""" ;
  14.     skos:altLabel """mortal""" ;
  15.     skos:altLabel """mortals""" ;
  16.     skos:altLabel """people""" ;
  17.     skos:altLabel """persons""" .

HTTP Status Codes

Here are the possible HTTP status (error) codes returned by this Web service endpoint.

  • Code: 200
    • Message: OK
  • Code: 400
    • Message: Bad Request
    • Message description: No source subject concept
  • Code: 406
    • Message: Not Acceptable
    • Message description: Unacceptable mime type requested
  • Code: 500
    • Message: Internal Error