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.
A partial list of terms defined in the API4KB ontologies:
Knowledge Platform (KP) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgePlatform
Knowledge Platform Manager (KP Manager) http://www.omg.org/spec/API4KB/API4KBTerminology/KnowledgePlatformManager
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.
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
The API4KB architectural elements are categorized according to the following competency questions.
See communication paradigms described in architecture styles.
For instance, client-server, peer-to-peer, agent architecture styles.
A description is a particular kind of Knowledge Resource that provides essential characteristics of an API4KB entity.
RDF is typically sufficient to express descriptions.
The API4KB ontologies define a vocabulary in the API4KB namespace for use in descriptions.
Foreign namespaces may also be used within descriptions.
Descriptions must be consistent with the metamodel (ontology), which provides restrictions on the domain, range and cardinality of properties in the API4KB namespace.
Descriptions adopt the semantics of RDF, especially the open-world assumption. This means that “violation” of a minimum cardinality restrictions in a description does not correspond to an inconsistency, but to either a lack of knowledge or a query for a partial description.
These codes are used in the following tables.
|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|
These CURIE prefixes are used in the following tables.
|:||http: API4KB namespace here|
|xsd:||http: XSD datatype namespace here|
 A Performative is an operation that is expressed directly in the knowledge resource. Languages with this capability include Prolog, RuleML and DOL. A knowledge resource containing performatives is an “executable knowledge resource”.
 The “hasDescription” property is a means to embedded information about the description in the description itself. Note that the subject of the “:hasDescription” property is the knowledge resource that the description is about, as named by the “:hasIdentifier” property.
 hasMetadata is itself a KnowledgeResource, and so extends the schema of some level of Knowledge Resource.
|tried (Try=Success or Failure)||N||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).
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.
E.g. IsCompatible takes an OMS Language and a Set of mappings.
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.
Add OMS to an existing (immutable) Knowledge Base to return a new (immutable) Knowledge Base.
Section 4.1. OMSs:
Section 4.3. OMS Annotation and Documentation:
Section 4.4. Structured OMSs:
Section 4.5. Mappings Between OMSs:
Section 4.6. Features of OMS Languages:
Section 4.7. OMS Language Serializations:
Section 4.8. Logic:
Section 4.9. Interoperability:
Section 4.10. Distributed OMSs and the Distributed Ontology, Modeling and Specification Language:
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.
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”.
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:
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:
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
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.
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:
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:
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]
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.
The descriptor for an Asset includes:
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)
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.
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:
Some KPM roles will depend on the ability to process queries.
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 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 :
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.
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 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/184.108.40.206 (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 &input=http://portal.gov/some.rdf"/> </api4kb:Request>
<?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 &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 &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 &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.