API4KB Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Goals =====
  * Describe the API4KB metamodel in an OWL ontology, to the extent that it is possible and reasonable to do so, making use of an OWL ontology from the DOL metamodel. 

===== Downloads =====
  * [[https://github.com/API4KBs/api4kbs|Master branch]]
    * This set of ontologies uses a design pattern where Actions, the atomic operations which are used to specify public operations, may have multiple inputs.
  * [[https://github.com/API4KBs/api4kbs/tree/currying|Experimental currying branch]]
    * This set of ontologies is an experiment to see if Actions can be all unary. This approach simplifies the internal interface, since a requested event can be specified by two parameters - the operation and the input. Public operations with multiple arguments are transformed to unary internal actions by currying, and this transformation serves as the specification of the public operation. See [[#currying]] for details.
  * [[https://github.com/ontohub/OOR_Ontohub_API/tree/master/lola/ontology|LoLa]]


===== Overview =====

Similarly to the message-oriented agent communication mechanisms defined in the FIPA specifications, the various APIs that comprise the API4KBs specification will only define the operations they are performing and the kinds of individuals involved in those operations. The specific details of an operation (e.g. the statement and the result type of a query) will be defined used the existing dedicated languages and encapsulated within the payload of an API4KB call. For some applications, within a specific ecosystem or architecture, there will be a handful, at most, of languages used across KBs and tools.  For others, such as research applications that require information from many sources, possibly over the web, the requirement for languages, including query languages, may be much broader.  The ontologies defined below are intended to provide sufficient information to drive the required operations using the set of languages that the knowledge bases in a given ecosystem understand.

===== Terminology =====
A partial list of terms defined in the API4KB ontologies:\\
Proficiency http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBProficiency/Proficiency\\
Roles http://www.omg.org/spec/API4KB/API4KBTerminology/Role\\ 
Operation http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/Operation \\
Events http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBEvent/Event \\
Components http://www.omg.org/spec/API4KB/API4KBTerminology/Component\\ 
Knowledge Platform (KP) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgePlatform\\
Knowledge Platform Manager (KP Manager) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgePlatformManager\\
Proxy http://www.omg.org/spec/API4KB/API4KBTerminology/Proxy\\
Client http://www.omg.org/spec/API4KB/API4KBTerminology/Client\\
Knowledge Resource http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeResource\\
Knowledge Base (KB) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeBase\\
Knowledge Asset http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeAsset\\
Knowledge Expression http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeExpression\\
Knowledge Manifestation http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeManifestation\\
Knowledge Encoding http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeEncoding.\\
Knowledge Item http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeItem.\\
Mapping http://www.omg.org/spec/API4KB/API4KBTerminology/Mapping.\\
Knowledge Representation and Reasoning Language (KRRLanguage) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgeRepresentationAndReasoningLanguage.\\

Entailment Regime: see http://www.w3.org/TR/sparql11-entailment/#entRegimeParts

===== Description Schemas =====
A description is a particular kind of Knowledge Resource that provides essential characteristics of an API4KB entity.

There are several key kinds of descriptions:
  - Descriptions of Knowledge Resources
  - Descriptions of Knowledge Platform
  - Descriptions of Knowledge Platform Managers

The (draft) schemas for these descriptions are shown below in matrix form.

==== Descriptions of Knowledge Resources ====
^ Key      ^ Value           ^
| Y        | Yes (exactly 1) |
| Y+        | Yes (1 or more) |
| Y?        | Optional (0 or 1)|
| Y*        | Yes( 0 or more)|
| N        | No  (exactly 0) |
| I[+?*]        | Inherited and Indirectly Available|



^ Property      ^ Asset       ^ Expression          ^ Manifestation          ^ Encoding          ^ IO          ^ Item          ^
| hasIdentifier  | Y?             | Y?                   | Y?                      | Y?                 | Y?           | Y?             |
| type       |KnowledgeResource|KnowledgeResource|KnowledgeResource|KnowledgeResource|KnowledgeResource|KnowledgeResource|
| level       | Asset          | Expression         | Manifestation          | Encoding          | IO          | Item          |
| usesPerformative[1]| Y*             | Y*                   | Y*                      | Y*                 | Y*           | Y*             |
| hasLocator     | Y?             | Y?                   | Y?                   | Y?             | Y?           | Y             |
| usesLanguage    | I+             | Y+                   | I+                    | I+                 | I+           | I+             |
| usesDialect     | N             | N                   | Y+                     | I+                 | I+           | I+             |
| usesFormat      | N             | N                   | N                      | Y+                 | I+           | I+             |
| usesStoreConfig | N             | N                   | N                      | N                 | Y+           | I+             |
| accordingTo (Environment) | Y             | N                   | N                      | N                 | N           | N             |
| isBasic     | Y             | Y                   | Y                      | Y                 | Y           | Y             |
| usesIOMode      | N             | N                   | N                      | N                 | Y           | N|
| hasMetadata    | Y?             | Y?                   | Y?                      | Y?                 | Y?           | Y?|
| selfDescription[3]    | Y?             | Y?                   | Y?                      | Y?                 | Y?           | Y?|

[1] Possible Performative values are Assertion, Retraction, Query, Result, ... 

[3] A self-description (of a knowledge resource) is a descripton embedded in the knowledge resource it is describing. It naturally inherits a number of properties from the knowledge resource being described, including level. Other properties are inherited unless overriden; e.g. language, dialect, format, storeConfig, IOMode, Metadata.
==== Descriptions of Knowledge Resources Property Values ====
^ Property      ^ Language       ^ Dialect          ^ Format                ^ StoreConfig        ^ Asset Environment    ^ Type    ^Level    ^Performative    ^Metadata[2]    ^
| hasIdentifier  | Y             | Y                   | Y                      | Y?                 | Y        |Y        |Y        |Y        |Y?        |
| hasLocator     | N             | N                   | N                      | Y?                 | Y?        |N        |N        |N        |[2]        |
| supports (Logic)       | Y             | I                   | I                      | I                 | I+       |N        |N        |N        |N        |
| usesLanguage    | N             | Y                   | I                      | I                 | Y+       |N        |N        |N        |[2]       |
| hasFocus (Language)       | N             | N                   | N                      | N                 | Y        |N        |N        |N        |N        |
| usesDialect     | N             | N                   | Y                      | I                 | N        |N        |N        |N        |[2]        |
| usesFormat      | N             | N                   | N                      | Y                 | N        |N        |N        |N        |[2]        |
| usesLocation    | N             | N                   | N                      | Y                 | N        |N        |N        |N        |N          |
[2] hasMetadata is itself a KnowledgeResource, and so extends the schema of some level of Knowledge Resource.

==== Descriptions of Applications ====

^ Property    ^  Proxy                ^ KP Manager  ^ KP    ^ Component ^
| hasIdentifier  | Y?                   | Y?         | Y?    | Y         |
| hasLocator     | Y?                   | Y?         | Y?    | N         |
| interactsWith (KP manager)  | Y*    | N          | Y?    | N         |
| interactsWith (Proxy)       | Y*    | Y*         | N     | N         |
| manages (KP)                 | I*    | Y*         | N     | N         |
| isSupportedBy (Component)  | I*    | I*         | Y*    | N         |
| isManagedBy (KPM)        | N     | N          | Y     | N         |
| fillsRole  | I*                   | Y*         | N     | N         |
| delegates (PublicOperation)    | Y*  | N          | N     | N        |
| implements (PublicOperation)   | I*  | Y*         | N     | N        |
| delegates (InternalOperation)  | I*  | I*         | Y*    | N        |
| implements (InternalOperation) | I*  | I*         | I*    | Y*       |


==== Descriptions of Applications Property Values ====

^ Property              ^ Role           ^ Proficiency          ^ Operation      ^ Event ^
| hasIdentifier            | Y?             | Y?                   | Y?             | Y? |
| hasLocator               | N              | N                    | N              | N  |
| requiresProficiency  | Y*             | N                    | N              | N  |
| exposesOperation     | I*             | Y+                   | N              | N  |
| isPublic             | N              | N                    | Y              | I  |
| isComposedOf (operation)| N          | N                    | Y*             | N  |
| hasEvent             | N              | N                    | Y?             | N  |
| hasEventRype        | N              | I+                   | Y+             | Y? |
| hasInput             | N              | N                    | I*             | Y* |
| hasOutput            | N              | N                    | I*             | Y  |


==== Descriptions of Messages ====

^ Property              ^ Request        ^ Response          ^
| hasIdentifier            | Y?             | Y?                |
| hasLocator               | N              | N                 |
| hasSender (Application)  | Y              | Y                 |
| hasRecipient (Application)| Y              | Y                 |
| try (Operation)          | Y              | Y?                 |
| input                    | Y*             | Y*                 |
| tried (Try=Success or Failure)              | N              | Y                 |


==== Descriptions of Message Property Values ====

^ Property              ^ Success          ^ Failure ^
| hasIdentifier            | Y?          |Y?          |
| hasLocator               | Y?          |Y?          |
| value                    | Y           |N          |
| explanation                  | Y?          |Y          |

==== Descriptions of Mutables ====

^ Property                 ^ Mutable[T]    ^ MutableKB     ^
| hasIdentifier            | Y?            |Y?            |
| hasLocator               | Y?            |Y?            |
| hasStateDescription      | Y             |Y             |
| hasHistory (Observable)  | Y?          |Y?            |

An Observable[T] is an Immutable Stream of items of type T that become available over time.\\
The history of a Mutable[T] is an Observable[T].\\
A MutableKB is a Mutable[ImmutableKnowledgeBase].\\
An ImmutableKnowledgeBase is a structured KnowledgeAsset (isBasic=false).\\


==== Descriptions of Observable Knowledge Resources (ObservableKR) ====

^ Property                 ^ ObservableKR   ^ View ^ 
| hasIdentifier            | Y?            |Y?            |
| hasLocator               | Y?            |Y?            |
| source (ObservableKR)      | -             |Y           |
| query  (QueryResource)   | -             |Y             |

 
===== Actions =====
Action http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/Action\\

Actions are Internal Operations that are Unary.
Lifting/Lowering Actions vertically traverse the Knowledge Resource abstraction levels.\\
Horizontal Actions have input and output that are at the same abstraction level.\\

Some API4KB operations are not unary. For example, lowering operations typically requires a parameter which specifies the output type (e.g. the dialect). These operations are specified in terms of the composition of actions through the use of higher-order actions.
Higher-order Actions have an action as either input or output (or both). The process of decomposing a function with multiple input arguments into a composition of unary functions is called currying.

The response to the request for an operation is contained in a wrapper of type "Try" . There are Accessor Actions that can be called to get the output Knowledge Resource (if it is a Success) and an Explanation.

Boolean-valued Actions.\\
E.g. IsCompatible takes an OMS Language and a Set of mappings.

Constructors.\\
  * the constructor for a KB takes as input a Set of OMSs and a set of Mappings and returns a Try of type KB
  * the constructor for a Success of type T takes a value of type T and a String (Explanation). 
  * the constructor for a Failure of type T takes a String (Explanation). 

Accessors.\\
  * GetOMSs takes a KB as input and returns a Set of OMSs as output. Note: Depending on the implementation, it may not be the same Set of OMSs that was input into the KB constructor.
  * GetMappings takes a KB as input and returns a Set of Mappings as output.
  * Get the value of a Success
  * Get the Explanation of a Try (Success or Failure)

Set Actions.\\
  * Add an object to a Set (e.g. add an OMS to a Set of OMSs, add an Expression to a Set of Expressions)
  * Create the union of two Sets

Sequence Actions.\\
  * Add an object to the head of a sequence
  * concatenate two sequences
===== Operations =====
Add Knowledge Resource  to an existing (immutable) Knowledge Resource to return a new (immutable) Knowledge Resource.\\
This is defined polymorphically (using coercion), depending on the type of the inputs.\\
The output type is always the same as the type of the second argument.
Particular forms of operations are defined (not necessarily how it is implemented) as a composition of Actions.

Add Item  to an existing (immutable) Knowledge Base to return a new (immutable) Knowledge Base.\\
  * Item is Instreamed to a Encoding
  * The Encoding is Unmarshalled to a Manifestation
  * The Manifestation is Parsed to an OMS
  * Call Add OMS to a KB.

Add OMS to an existing (immutable) Knowledge Base to return a new (immutable) Knowledge Base.\\
  * GetLanguage: Get the OMS Language of the OMS
  * GetMappings: Get the Set of Mappings of the KB
  * IsCompatible: Check the compatibility of the OMS Language with the Set of Mappings
  * If True, GetOMSs of the KB,
  * Add the OMS to it,
  * and call the KB constructor on the extended Set of OMSs and the Set of Mappings.
  * Return a (new) Success wrapping the new KB and an Explanation.
  * If False, return a (new) Failure wrapping an Explanation.



Querying

===== Terminology from OntoIOp =====

Section 4.1. OMSs:

  * OMS (ontology, specification or model)
  * OMS language: e.g. OWL, Common Logic, F-Logic, UML class diagrams, RDFS and OBO.

Section 4.3. OMS Annotation and Documentation:

  * annotation 
  * OMS documentation

Section 4.4. Structured OMSs:

  * basic OMS
  * structured OMS
  * subOMS
  * extension
  * approximant, uniform interpolant

Section 4.5. Mappings Between OMSs:

  * OMS mapping, linkOMSs
  * union
  * combination

Section 4.6. Features of OMS Languages:

  * OMS language translation
  * sublanguage
  * language aspect
  * logical language aspect
  * structuring language aspect
  * annotation language aspect
  * profile

Section 4.7. OMS Language Serializations:

  * serialization
  * standoff markup

Section 4.8. Logic:

  * logic
  * institution
  * logic translation
  * logic reduction
  * logic approximation
  * sublogic
  * heterogeneous OMS

Section 4.9. Interoperability:

  * logically interoperable

Section 4.10. Distributed OMSs and the Distributed Ontology, Modeling and Specification Language:

  * distributed OMS, hyperontology
  * distributed ontology, modeling and specification language, DOL

==== OntoIOp Competency Questions ====
  - ... 4.1 ...
  - What language(s) is OMS "http://example.org/myOMS" expressed in?
  - ... 4.3 ...
  - Is the resource "http://example.org/myOMS#comment1" an annotation of OMS "http://example.org/myOMS"?
  - What are the URLs of the OMS documentation of "http://example.org/myOMS"?
  - ... 4.4 ...
  - Is OMS "http://example.org/myBasicOMS" a basic OMS?
  - What are the subOMSs of the structured OMS "http://example.org/myStructuredOMS"?
  - Is OMS "http://example.org/myStructuredOMS" an extension of "http://example.org/myBasicOMS"?
  - Is OMS "http://example.org/myTripleStore" an approximant of "http://example.org/myOntology"?
  - ... 4.5 ...
  - Is "http://example.org/myMapping" a mapping from OMSs "http://example.org/myOMS1" to "http://example.org/myOMS2"?
  - Is OMS "http://example.org/myOMS1" the union of OMSs "http://example.org/myOMS2" and "http://example.org/myOMS3"?
  - Is OMS "http://example.org/myOMS1" the combination of OMSs "http://example.org/myOMS2" and "http://example.org/myOMS3"?
  - ... 4.6 ...
  - Is OWL RL a sublanguage of OWL Full?
  - Is RDF a sublanguage of OWL?
  - What are the profiles of OWL?
  - ... 4.7 ...
  - Is "http://example.org/myOMS.owl" serialized in valid Manchester OWL RL?
  - What is the URL of the standoff markup of http://example.org/myOMS"?
  - ... 4.9 ...
  - Is the logic of RDF a sublogic of the logic of OWL Full?
  - ... API4KB
  - What is the type of a SPARQL endpoint?




===== Languages =====

The key entities where languages are specified directly in the Description are: KnowledgeExpression and AssetEnvironment. 

In some cases, relevant language may be obtained indirectly, e.g. from a KnowledgeManifestation in the XCL2 dialect, then because of the dialect it is clear that the Common Logic language is relevant. Similarly format (more precisely KRRFormat) is based on a specific dialect, which is related to a specific language. This kind of indirect language specification is appropriate for all knowledge resource levels lower than Expression, i.e. Manifestation, Encoding, IO, Item.

At the KnowledgeAsset level, language information is obtained indirectly from the AssetEnvironment, which is a structure of KRRLanguages and mappings between them.


===== Knowledge Bases =====

The use of the term "knowledge base" from an API4KBs perspective is quite broad, and represents more than simply a storage facility.  Storage is one of a number of capabilities that a given "knowledge base" might have.  For the purposes of the sections that follow and the model that we are proposing, the term "knowledge platform" is used to reflect this broader notion of what we formerly called a "knowledge base".
===== Particular Descriptors =====

==== Knowledge Platform Manager ====

A knowledge platform (KP) manager provides the "active" component of the architecture, whereas the KPs themselves are "passive" (i.e., their roles / capabilities must be initiated through a KP manager).  KP managers may perform any number of roles, where a role encompasses a meaningful set of capabilities, exposed as interfaces through the APIs, whose functionality is provided via sets of components.  These roles and related components are specified in corresponding KP Manager Role and Component ontologies. A Role is equivalent to a set of APIs, which is a subset of the full list of API4KBs. Any KP manager can implement a subset of the totality of roles defined overall for API4KBs. However, a Role must be implemented atomically: all the APIs associated to that Role must be implemented, otherwise the KP Manager will not be able to play that role. The high-level capabilities that a given KP manager can provide are constrained by two things: (1) the APIs that the manager implements, and (2) whether or not any of the KPs it manages can provide those capabilities (a given KP may or may not allow various capabilities or roles).  The individual components, defined in the Components ontology, provide lower level "proficiencies", specified in a corresponding Proficiency ontology, and can be combined or composed to provide higher level capabilities/roles.
 
The descriptor for a Knowledge Platform Manager (KPM) includes:

   * descriptor metadata (i.e., self-describing information about the KPM descriptor -asset- itself, such as the version of the descriptor)
   * knowledge platform manager metadata (i.e., aside from the specific capabilities/roles it has, such as ownership/stewardship, version, availability, etc.)
   * an instantiation of the roles the KP manager can perform via the roles ontology (i.e. its capabilities), per the APIs it implements - optionally including, but not limited to the ability to implement or delegate messages containing requests regarding
     - (KP Container / Warden) return the IDs of the KP accessible (to the user) using this KP manager, 
     - (KP Discovery / Finder) find relevant KPs by description, 
     - (KP Manager Mutator (or Warden) - Persistent Create) register a KP with a KP manager so that 
         * the user, or others can access it later (C of CRUDE), 
     - (KP Manager Mutator (or Warden) - Delete) remove a KP from the KP Manager (D of CRUDE)  
     - (KP Manager Factory / Builder) create a new KP manager 
   * a reference or references to zero, one, or more additional ontologies that are used to define additional metadata and / or are specifically of interest //to the user// in accessing a particular KP manager (for example, information regarding coverage and scope within a particular domain)


To be considered a KP Manager, an entity must have at least one of the above roles. There are additional roles that a KP Manager may have, but these are not sufficient for an entity to be considered a KP Manager:
     - (KP Factory / Builder) create a new (temporary) KP, including 
         * a virtual KP consisting of a collection of separate KPs 
         * a reconfiguration of an existing KP as a new KP
     - (KP Mutator / Warden / Abstractor / Transformer / Configurator) change the contents or other characteristics of a KP
     - (Organizer) provide semantic indexing over the KP
     - (Integrator / Mediator) act as mediator between multiple KPs
     - (Recommender) provide recommendation facilities
     - (Reasoner)
     - (Transformer)
     - (Validator) validate the contents of a KP     - ...

The required information in a knowledge platform manager descriptor shall be applicable to "sub-KP" managers whose content is a subset of its contents. Delegation models are allowed.

The descriptor is not required to include the knowledge platform manager identifier because a sub-KP manager must have a different identifier.

Ontologies are needed to define terminology used in KP Manager Descriptors, including
    - terms describing a KP, (it's "proficiencies") for discovery
       * supported styles of reasoning
       * representation languages supported
       * the semantic expressivity needed to express the contents of the KP (i.e., the logic it supports)
       * serialization formats that a KP has the capability to express its contents in
       * analysis and transformation capabilities of a KP
       * the subject matter of the KP 
    - terms describing the synthetic capabilities of a KP Manager
       * to merge the contents of one or more KPs
       * to filter the contents of a KP

The minimum set of ontologies will define (1) Roles, (2) Proficiencies (i.e., those required / available to be combined or composed to provide the capabilities for a given role), (3) Components -- defining the building blocks that a KPM can use/access/instantiate/etc.. in the KP(s) it manages. The Components will provide the granular proficiencies that are available to be combined to deliver higher-level proficiencies at the KP level. The KP proficiencies will determine which roles are supported by the KPM and how, and (4) Asset Specifications, including specifications of descriptors as assets, query assets, etc.

Example: A KP Manager has the "Translator" Role, which is defined in terms of the parsing and translation APIs. It manages a KP where the only Component is a translation service, whose only Proficiency is the ability to translate ontologies between ontologies expressed in OWL-DL (any format) to Common Logic (any format). The translation APIs delivers an input asset, which contains the source ontology, and a descriptor which contains the specification of the asset (e.g. OWL-DL in Manchester Syntax), as well as a descriptor containing the desired specification. The response will contain the output asset with the result of the translation, a descriptor with the actual output specification, and an "explanation" describing to what extent the operation was successful.
==== Knowledge Platform ====

A knowledge platform may be a store, accessible via a SPARQL endpoint or some other means, or a more complex platform such as a reasoned or rule engine that may or may not provide inherent store capabilities.  In general, a KP is managed by a KP manager, and is built with one or more Components that determine its proficiencies. The descriptor for a Knowledge Platform (KP) includes:

   * descriptor metadata
   * knowledge platform metadata
   * knowledge platform proficiencies - optionally including, but not limited to the ability to implement or delegate messages containing requests regarding the KP.
       *  a user who sees a KP at all should be able to request the KP's proficiencies (for them), so this minimal level of access is implicit
   * a reference or references to zero, one, or more ontologies that are used to define the metadata and / or are specifically of interest to the user in accessing a particular KP 

To be considered a KP, an entity must have at least one of the above proficiencies. There are additional proficiencies that a KP may have, but these are not sufficient for an entity to be considered a KP:
   * allowing execution of certain analyses on the contents of a KP (E of CRUDE, because the KP supplies the required proficiencies)


Some Roles of a KPM depend strictly on the KP and its ability to manage content (assets) : [The list needs to be cleaned up, based on the roles that we will eventually define]
       * (Asset Container / Warden) read (some) Assets in the KP contents, possibly constrained by certain rules such as formats in which the asset is serialized
       * (Asset Discovery / Finder) looking up information regarding specific assets in a KP, by ID or by Asset Description
       * (Asset Factory / Builder) create new Assets 
       * (Validator) syntactic validation of a given KP, 
               * (...) semantic validation (e.g. consistency or constraint checks) of a given KP, 
       * (Reasoner) reasoning (forward chaining, backward chaining, tableaux), on the contents of a given KP, relative to a Query
       * (Approximator / Transformer) approximate Assets or Querys in a language of lesser expressivity
       * (Abstractor / Refiner / Transformer) abstract / map Assets to a higher level of abstraction or refine / map Assets to a lower level (more constrained, detailed) of abstraction for use in alignment with other systems or Assets
       * (Analyser) perform some analysis task on one or more Assets or over the entire KP or a partition thereof
       * (KB Mutator / Warden) change the contents of a KP (add, delete Assets from the KP) (U of CRUDE)
       * some KPs may be immutable, and so there is no write access. In that case, the capability of a KP factory (builder) to create new KPs based on the contents of some other KP is more relevant  


The proficiencies and set of components required to deliver them are defined in proficiencies and components ontologies, respectively.  Asset specifications, including specifications for query assets, are defined in an asset specification (ontology).

The required information in a knowledge platform descriptor shall be applicable to "sub-KP"s whose content is a subset of its assets.

The descriptor is not required to include the knowledge platform identifier because a sub-KP must have a different identifier.
==== Asset ====

The descriptor for an Asset includes:

   * descriptor metadata
   * asset metadata, as described in its specification (using the Asset ontology), including but not limited to the set of proficiencies required to process/work with it
   * asset proficiencies - optionally including, but not limited to the ability to implement or delegate messages containing requests regarding
       - reading the asset
           * a user who sees an asset at all should be able to request the asset's proficiencies, so this minimal level of access is implicit
           * read access may be subject to certain constraints, such as the format(s) in which the asset is serialized
           * a reference or references to zero, one, or more ontologies that are used to provide additional metadata, and domain knowledge / terminology relevant to working with a particular asset

Some roles of a KPM will be defined in terms of the operations that it can execute on assets (usually with the support of some Component in the KP)
       - (Asset Mutator) change an Asset (U of CRUDE)
           * some Assets may be immutable, and so there is no capability to change them. In that case, the capability of some entities to create new Assets based on some other Asset is more relevant

When querying for assets, a subscriber or user may specify required and desirable proficiencies (e.g. assets that can be used in a certain way, or for some purpose e.g. classification) and specifications (e.g. assets serialized in a specific format). Any asset retrieved by the KPM and returned should respond with the set of specifications that it actually has.  The distinction between required and provided proficiencies/specifications is something that can only be determined by the KP(M), based on a combination of its own proficiencies and the specifications of the assets it has access to or holds.  Available proficiencies should something the subscriber or user should be able to determine via queries of the KP manager, so that requests can be optimized: ideally the intersection between the desired and available profs/specs should not be null.

An asset may have inherent proficiencies, implied by their specification, and/or may have proficiencies that are only available if the asset is managed on a specific KP platform.  These proficiencies could be declared, as a part of the asset specification, or inferred from its format and KP together.  The asset specification will determine how its content must be handled, including required proficiencies for processing it.  In other words, based on the specification we should be able to infer the minimum set of proficiencies required to manage, use, and transform it.  If no explicit proficiencies are stated in an asset specification, some of these features or capabilities should be inferable from the KP's proficiencies and feature set, in particular, any that are required.  Any proficiencies over and above those required for asset handling would fall into the category of "desired" proficiencies".

Note that all descriptors are also considered assets of sort, and should be self-describing using the asset ontology.  High-level descriptors may also incorporate in-line assets / asset specifications and/or descriptions.

==== Query ====

Queries are considered assets. Query APIs will deliver query (assets) as their payload and implicitly request to trigger reasoning to answer those queries. Otherwise, queries will be stored as assets for later use or retrieval. There is no separate query descriptor -- it uses the same descriptor as that of an asset specification, where the specification states required proficiencies, includes the language form, determines the reasoning requirements and states additional desires (in the case of dynamic as opposed to static/canned queries), and so forth.  The descriptor for a query includes:

   * descriptor metadata
   * query-specific specification, such as the language, format,
   * query-specific proficiencies: reasoning style, how results are to be returned, level of explanation desired, etc.
       - read the query
           * a user who sees a query at all should be able to request the query's capabilities (for them), so this minimal level of access is implicit
   * a reference or references to zero, one, or more ontologies that are used to define domain knowledge and terminology that might be appropriate for the set of KP platforms targeted by the query

Some KPM roles will depend on the ability to process queries.
       - (Query Mutator) change the Query (U of CRUDE)
           * some Querys may be immutable (such as canned/stored queries that are required for the operation of some set of proficiencies) and so there is no facility to change them. In that case, the capability of some entities to create new Querys based on some other Query is more relevant

The query API must be able to use the specification for the query and other input in the form of the descriptor to determine both input and output requirements.  This may entail the need for assets that describe output forms and formats that the user can select together with the query itself to fully describe not only the information desired but the form the results should take.

Within the context of a descriptor, there may also be references to formulas / rules, and/or sentences that use the ontologies, specifications, and proficiencies via the available components to build up to the desired complex execution instructions.


==== Explanations ====

Explanations have not yet been discussed in depth. Some material is included here for comments.

Explanations will be defined at two levels (as most other elements).

The "outer" explanation will provide information such as :
   * the outcome of an API call (success, failure, partial success for best-effort operations, etc...)
   * the Components involved
   * ...
Example : A "store asset" explanation might describe which Component (store) of a KP has chosen and why - e.g. load balancing vs the only one which had the required proficiencies to support the asset.
Example : A "execute query" explanation result might describe which reasoners have been invoked on which knowledge base. 

The "inner" explanation will trace how the output of the operation was generated. It could use a native trace format, or use standard such as Proof Markup Language.
In general, this trace should be considered an asset (?) on its own.

===== Ontology and Rule Language Vocabulary =====

In order to make a request of a particular knowledge base, ontology, or rule set, one must specify the language to be used (its semantics), any specifics regarding the dialect or profile required (e.g., OWL RL, OWL DL), and how it is encoded (the syntax required to access it).  This vocabulary is intended to provide an initial set of languages, their features and capabilities, and the various syntactic forms that those languages can take.  Implementations can take a variety of forms, and it is not our intent to provide an exhaustive set of descriptions for every possible language users might be interested, but instead to provide mechanisms for pointing to or referencing unique identifiers for these languages in a given setting.  One such target setting is for use by the OntoIOp proposed standard and related projects, but we can imagine many others.

Within the scope of this effort, we've identified two somewhat overlapping needs: (1) to be able to unambiguously identify the language, variant, and syntactic form of a language supported by a given knowledge base or in which a given ontology is encoded, and (2) to be able to classify languages and ontologies to a degree that is useful in mapping capabilities and transformations.  This second goal is one that we know, from the outset, will be simply that, a goal, and that the classification facilities provided in an ontology developed for API4Kbs and OntoIOp will necessarily be incomplete.  Only experience with the requirements for and use of the classification capabilities will help determine whether what we have done is adequate to the task, and we anticipate that the resulting ontology will need to be designed to evolve over time.

===== Currying =====
Currying is a mapping between functions that takes an n-ary function, f(a,b) to a sequence of applications of unary functions g(a)(b).

If API4KB actions are unary through currying, then an internal rest call (the call made by the Proxy to the KP Manager) may have a uniform template:

  http://example.org/...?action=(some IRI)&input=(some IRI)

Each of the two IRIs in the query string can again be API4KB rest calls. If the action IRI is an API4KB rest call, that indicates currying. If the input IRI is an API4KB rest call, that indicates composition.

Example 1. A single action GET request

  http://example.org/myKnowledgeServer?
    action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/InStreamingAction&
    input=http://portal.gov/some.rdf

This IRI is the identifier for the result of the action. In practice, the KP Manager could cache the byte sequence resulting from the action, and make use of it whenever this IRI is utilized, instead of repeating the instreaming. For this action (a lifting action), the input is expected to be an immutable knowledge resource, so there is no need for the action to ever be repeated (as long as the cache is intact). (If the input is mutable, then a different operation is needed, where a snapshot of the mutable source is taken and then the snapshot, which is an immutable resource, is instreamed.)

The above describes a [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3|GET] request.

The actual syntax of the GET request is (with ... to abbreviate the long URL)

  GET /myKnowledgeServer?action=.../InStreamingAction&input=...some.rdf HTTP/1.1
  Host: example.org
  Accept: application/octet-stream
  Cache-Control: public

The server response would be something like

  HTTP/1.1 200 OK
  Date: Mon, 23 May 2014 22:38:34 GMT
  Server: Apache/1.3.3.7 (Unix) (Red-Hat/Linux)
  Last-Modified: Wed, 08 Jan 2013 23:11:55 GMT
  ETag: "3f80f-1b6-3e1cb03b"
  Content-Type: application/octet-stream
  Content-Length: 131
  Accept-Ranges: bytes
  Connection: close

followed by the byte stream.

Note - this request does not create a permanent storage in the way that PUT does.
So the effect is to create an alias on the server for the external resource,
with the byte sequence in cache. This resource cannot be modified, and this is
appropriate for immutable resources.

Example 2. Composition of two actions: InStreaming and Unmarshalling

The API4KB notion of UnmarshallingAction is not just a matter of converting the byte stream to some character sequence, but also extracting from archives, if the input is compressed. 
Such a result cannot be sent back in a message without recompressing it, which defeats the purpose. 
Therefore this request should be implemented as POST:
  
  POST /myKnowledgeServer HTTP/1.1
  Host: example.org
  ...  
  <?xml version="1.0" encoding="UTF-8"?> 
  <api4kb:Request>
    <api4kb:action cri="api4kb:UnmarshallingAction/>
    <api4kb:input cri="http://example.org/myKnowledgeServer?
                       action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/InStreamingAction
                       &amp;input=http://portal.gov/some.rdf"/>
   </api4kb:Request>
   
or perhaps 
   
    <?xml version="1.0" encoding="UTF-8"?> 
    <api4kb:Request>
      <api4kb:action cri="api4kb:UnmarshallingAction"/>
        <api4kb:input>
          <api4kb:Request>
            <api4kb:action cri="api4kb:InStreamingAction"/>
            <api4kb:input cri="http://portal.gov/some.rdf"/>
          </api4kb:Request>
        </api4kb:input> 
    </api4kb:Request>

       
  
The response should be the descriptor of the created resource. 
The response code should be 201 if the resource has been successfully created.

  ...
  Location: http://example.org/myKnowledgeServer?
    action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/UnmarshallingAction
    &input=http://example.org/myKnowledgeServer?
      action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/InStreamingAction
      &amp;input=http://portal.gov/some.rdf
  ...

Example 3. Application of two curried actions: Manifesting to a Specified OWL Serialization
    
As in Example 2., the output of this operation, a Knowledge Manifestation, is not delivered in the response.
Therefore, this operation is best implemented as POST.

  POST /myKnowledgeServer HTTP/1.1
  Host: example.org
  ...
  <?xml version="1.0" encoding="UTF-8"?> 
  <api4kb:Request>
    <api4kb:action>
        <api4kb:Request>
          <api4kb:action cri="api4kb:ManifestingConfigurationAction"/>
          <api4kb:input cri="owl:ManchesterSyntax"/>
        </api4kb:Request>
    </api4kb:action>
    <api4kb:input cri="http://example.org/myKnowledgeServer/MyOWLOntology/"> 
  </api4kb:Request>

The response should be the descriptor (better description?) of the created resource. 
The response code should be 201 if the resource has been successfully created.

  ...
  Location: http://example.org/myKnowledgeServer?
    action=http://example.org/myKnowledgeServer?
             action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/ManifestingConfigurationAction
             &amp;input=...ManchesterSyntax
    &input=http://example.org/myKnowledgeServer/MyOWLOntology/
  ...
  
Example 4. Application of two curried actions: Adding a Knowledge Expression to a Immutable KB

  POST /myKnowledgeServer HTTP/1.1
  Host: example.org
  ...
  <?xml version="1.0" encoding="UTF-8"?> 
  <api4kb:Request>
    <api4kb:action>
        <api4kb:Request>
          <api4kb:action cri="api4kb:Action-AdditionOfExpression-HorizontalAssetActionOut"/>
          <api4kb:input cri="this:CLTextA/"/>
        </api4kb:Request>
    </api4kb:action>
    <api4kb:input cri="this:MyKB1/"> 
  </api4kb:Request>

The response should be the descriptor (better description?) of the created resource. 
The response code should be 201 if the resource has been successfully created.


  ...
  Location: http://example.org/myKnowledgeServer?
    action=http://example.org/myKnowledgeServer?
             action=http://www.omg.org/spec/API4KB/API4KBTerminology/API4KBOperation/Action-AdditionOfExpression-HorizontalAssetActionOut
             &amp;input=http://example.org/myKnowledgeServer/CLTextA/
    &input=http://example.org/myKnowledgeServer/MyKB1/
  ...  
  
  
Note: the XML and CURIE prefixes need to be defined in these XML message payloads.

===== References =====

  * Foundation for Physical Intelligent Agents (FIPA) Agent Communications Language (ACL) - http://www.fipa.org/repository/aclspecs.html
  * Indiana Philosophy Ontology - https://inpho.cogs.indiana.edu/
  * ISO 11179-3 Metadata Registration Standard, and related ISO 19763 Model Registry Standard - http://www.metadata-standards.org/
  * LATIN Project Logic Atlas - https://trac.omdoc.org/LATIN
  * LoLa ontology from the OntoIOp project -  http://www.informatik.uni-bremen.de/agbkb/forschung/formal_methods/CoFI/hets/dol/logics/ 
  * Meta-Ontology for Ontology Categories - http://ontolog.cim3.net/file/work/OpenOntologyRepository/OOR-categories/2013-10-08_MetaOntology-for-Ontology-Categories/MetaOntology-for-Ontology-Categories--AleksandraSojic_20131008.pdf and http://ontolog.cim3.net/cgi-bin/wiki.pl?OOR/ConferenceCall_2013_10_08
  * Ontology Metadata Vocabulary (OMV) - http://omv2.sourceforge.net/
  * OntoMaven - http://www.corporate-semantic-web.de/ontomaven.html
  * Open Knowledge Base Connectivity (2.0.3) - http://www.ai.sri.com/~okbc/okbc-2-0-3.pdf
  * OSLC Metadata Management - http://www.oclc.org/research/activities/msm.html
  * The Proof Markup Language (PML) and Inference Web - http://inference-web.org/
  * The W3C Provenance Ontology (prov-o) - http://www.w3.org/TR/prov-o/
  * RuleML myng Page - http://ruleml.org/1.0/myng/
  * The Specification Metadata Ontology from the OMG - http://www.omg.org/techprocess/ab/SpecificationMetadata.rdf
  * JSR-000094 Java(TM) Rule Engine API 1.0a Final Release  http://download.oracle.com/otndocs/jcp/jreng-1_0a-fr-spec-api-oth-JSpec/
API4KB Wiki

User Tools

Site Tools

Page Tools
