The current definition is much more specific than desirable - there should be a general notion of knowledge, of which concept and 'body of knowledge' (or some equivalent term) should be subclasses. If we do this, then mapping the API4KP and MVF ontologies would be much cleaner.

The relationship between body of knowledge and concept should then be clarified as well.

The Expression::result property in the KerML abstract syntax is suppose to subset Step::parameter, where Step is a superclass of Expression. However, in the normative KerML.xmi it is erroneously specified as subsetting Behavior::parameter, which is a different property than Step::parameter. Further, Behavior is not a direct or indirect superclass of Expression, so the subsetting is invalid in MOF/UML.

(Note that this error is not apparent in the specification document, because, in the annotation for subsetting, the subsetted parameter is shown without qualification – e.g., just parameter, not Behavior::parameter.)

The initial version of API4KP was based on swagger 2 with the canonical transformation from 2 to 3. A better approach at this point is to start from swagger 3, which has more capabilities and is more modern.

The resolution impacts the specification as well as several of the machine-readable files.

The mapping back to swagger 2 may be lossy if we take advantage of new features, so for the RTF we will simply swap the order of operations and defer a more comprehensive approach to a 2.0 update to API4KP.

There are four new ontologies in Commons that contain terms that could be used / reused in the API4KP ontologies. Better alignment would facilitate use of the APIs with knowledge graphs that implement the Commons ontologies. This update would primarily impact the ontologies themselves, although there may be some revision to the specification where the ontologies are documented as well.

API4KP uses a tunneling approach where 'models' of various nature are wrapped in an API4KP "KnowledgeCarrier" object that adds some necessary metadata about the model.

Implementations that require transport (e.g. based on ReSTful web services) face two problems:

• the serialization format of the wrapper (JSON, XML or else)
• the representation and serialization of the model (in various languages, across serializations and formats)

The former is a classic content negotiation problem, and is expetcted to be handled in the standard way, using Accept-* and Content-* headers

The latter is a similar but distinct model negotiation problem. The standard mandates not to use the content negotiation headers - so that, for example, a BPMN+XML model can be serialized and embedded in an API4KP+JSON KnowledgeCarrier.
Insteadd, API4KP model negotiation defines an "X-Accept" header for requests, and uses the KnowledgeCarrier body itself for the analogue of the Content-Type response.

The use of a header, as opposed to a query parameter, has pros and cons, and should be discussed.
Ultimately, it comes down to the ability to provide a (persistent) URL to a specific knowledge artifact, using a primary identifier composed by the ID of the carried knowledge Asset, plus a coded identifier of the artifact's form

Options:
(1) keep xAccept as it is
(2) replace xAccept w/ qAccept
(3) add qAccept as an optional parameter, together with xAccept

I am strongly inclined towards (3), for this reason:

• {assetd}/carrier
  return (any) "canonical" model form
  
  * {assetd}

  /carrier ? qAccept=formB
  return model form B specifically

• {assetd}/carrier
  xAccept=formB
  retrieve or generate formB using any form available
  
  * {assetd}

  /carrier ? qAccept=formA
  xAccept=formB
  retrieve formA, and use it to generate formB if not the same

Background references:

https://softwareengineering.stackexchange.com/questions/250602/why-doesnt-the-html-dom-specification-allow-hyperlinks-to-set-an-accept-heade
https://stackoverflow.com/questions/374885/can-i-change-the-headers-of-the-http-request-sent-by-the-browser

This includes any diagram changes required based on changes to the ontologies themselves through migration to the Commons Ontology Library as well as updates to dependency tables, e.g., on page 48, and relevant metadata.

Revised documentation for the ontologies in the specification

This issue primarily affects Annex A, with minor changes to references. Although very little of the text changes, the images in the ontology section have been revised and new images added where there were gaps. Note that there is no image for the relations ontology as it does not define any new classes.

These are scattered about in the ontology, and should become subproperties of or be defined in terms of the commons 'uses' property.

This issue only impacts the ontologies, not the specification at this point.

Restructured a number of concepts and properties related to language / linguistic entities

This resolution impacts the ontologies only. Documentation for the ontologies will be addressed under API4KP-23.

Two ontologies were affected by this resolution: api4kp.rdf (the main ontology) and api4kp-lang.rdf. The changes involve a handful of updates to better align some of the properties related to language handling in API4KP, including, to the main api4KP ontology:

• separation of the dependency between hasSublanguage and embedsLanguage, including renaming embedsLanguage --> supportsEmbeddedLanguage
• making dol:Language subClassOf lcc-lr:Language rather than equivalent to it
• added api4kp:usesLanguage
• added property api4kp:supportsFormat, domain dol:Language, range api4kp-lang:metaFormat

To the api4kp-lang ontology:

• changed 'api4kp:defines some lcc-lr:language' to 'api4kp:defines some dol:formal language'
• create new 'api4kp-lang:supportsSerialization' sub-property of 'api4kp-lang:hasGrammar', with super-property of 'dol:supportsSerialization', domain dol:language and range api4kp-lang:Serialization
• create new 'api4kp-lang:supportsFormat' as a sub-property of 'api4kp-lang:hasGrammar' and sub-property of 'dol:isLinguisticallyRelatedTo', with domain dol:language and range api4kp-lang:MetaFormat

This issue impacts the ontologies which are described in Annex A. There will be subsequent revisions to the ontologies and thus we will update the documentation in Annex A in a separate issue.

This is primarily about replacing the URIs of the relevant properties with those in the commons, including the dependencies in the table on page 50.

Revised the various ontologies to reuse the commons ontologies rather than specification metadata and LCC

1. In the ontology namespace declarations, remove references to Specification Metadata and replace them with the Commons Annotation Vocabulary, and replace references that use it in the ontology metadata, including imports statements
2. Update the version IRI to 20230201, corresponding to the 4-week rule for the March 2023 meeting
3. Replace references in the ontology header that reused properties from Specification Metadata with those from the commons annotation vocabulary and eliminate those that are no longer relevant/needed.
4. Add the namespace and imports for the Codes and Code Sets, Collections, Contextual Designators, Designators, and Identifiers ontologies where appropriate to reuse properties from the commons rather than from LCC.
5. Replace concepts and properties in API4KP ontologies where there is a corresponding element in Commons.

The IDL should be changed to match the UML model. This includes:
All sequences are defaulted to infinite range, but many should be [0..1]
Many structure fields have cardinality [1], but should be [0..1]
Most IDL sequences are not used and should be removed
All UML enumerated types should correspond to IDL as enumerated types
The UML model defines classes with attributes and no operations. They should instead be represented by a simple data structure with fields. If one of these non-behavioral classes uses inheritance; the resulting "subclass" data structure type should contain an additional field that has a type of the "superclass" type.

The IDL was resynchronized under the resolution to API4KP-19

While addressing the IDL was considered important to the FTF, it required the changes involved in API4KP-19 and thus has been addressed under that issue.

The spec defines an api4kp:services:error datatype class used to wrap error messages..

A better, and standard, datatype for this very purpose is defined in https://www.rfc-editor.org/rfc/rfc7807. API4KP should reuse this datatype rather than creating something unique that is non-standard.

The datatype is also missing from the specification document and should be covered therein.

Use of RFC 7807 has been accomplished via the resolution to issue API4KP-19

The changes required to address this issue have been done under the issue to revise the way that datatypes are handled and thus this issue is considered a duplicate.

ISO 1087 was revised in 2019 and our definitions should reflect any relevant changes as well as the references.

This change impacts the ontologies only, not the specification document.

Revise the references to ISO 1087 in the ontologies to reference and use definitions from the latest version

Due to replacement of a number of terms under API4KP-22 with their equivalents in the Commons Ontology Library 1.0, only a couple of references to the older version of the ISO 1087 standard remained. These references were changed to reflect the latest version from 2019.

The API4KP section 7.2.3 is underspecified and should cover all of the datatypes needed for the APIs, including diagrams.

Revise the specification for datatypes in general

The approach taken to representation of datatypes in UML proved to be less than satisfactory from an implementation perspective, and has been substantially revised via this issue.

The critiques can be grouped in three (plus one) categories:

• (a) The use of UML tooling. The original specification was built using a tool (UMLDesigner) which is based on the Eclipse UML framwork. Moreover, UMLDesigner development has been abandoned, rasining concerns of compatibility and sustainability.
• (b) The use of UML modeling constructs. We have used UML for a very specific purpose: defining datatypes ("structures") used for transport of information at the API layer.
  The specification of operations, domain specific conceptualizations and classes/components designed for the internal implementation of Knowledge Platform services has been done in different models, or left out of scope. The intent of the datatype model, instead, has been to provide a core PIM model that could be easily mapped to a variety of PSM frameworks.
  As it turned out during implementation, the intersection of the most common PSM frameworks is fairly narrow, For example, IDL datatypes do not support (multiple) implementation inheritance, but require the use of type inheritance via interfaces instead. JSON schemas can emulate (multple) implementation inheritance via 'allOf', but multiple inheritannce is not supported in XML schemas... Similar issues arise when using certain primitiive datatypes, or trying to enforce certain schema constraints.
• (c) The completeness of the model. Since the original revision, certain datatype (or elements thereof) have turned out to be more useful than others. Conversely, other datatypes turned out to be underspecified, such as "Error".
• (d) The documentation of the model was generally lacking details

All things considered, it was deemed appropriate to revise the datatypes altogether. The API / datatype boundaries have been left mostly untouched, with the exception of some consolidations detailed below. Instead, the bulk of the work has focused on reshaping the internal details. In doing so, we have taken into account emergent standards and best practices which did not exist at the time of the original specification.
More specifically, to address the critique points:

• (a) We have rebuilt the datatype model as a UML 2.5.x model using MagicDraw. The model has then been exported as a 'clean XMI' document for portability
• (b) We have rebuilt the model using a more parsimonious approach. Interfaces, inheritance and constraints have been removed, as they turned out not to be necessary for the goal at hand, and would have not been supported by the downstream implementations. We have taken an even more radical approach, limiting the model to the use of primitive and structured datatypes, with no classes nor operations. The rationale behind this choice is that the API4KP datatypes do not represent identifiable Resources, and do not capture behavior themselves (i.e. they are not "objects"), but rather data structures used to describe, wrap or support operations on Knowledge Resources. As a side effect, this sober modeling approach is more likely to be universally mappable
• (c) We have performed a retrospective analysis of the 5year long implementation at Mayo Clinic, which has led to 12+ server implementations of the 5 API4KP service interfaces, and 30+ implementations of the API4KP atomic operations, as well as the extrapolation of the methodology to other APIs beyond API4KP. We have looked at PSM options - namely Java, C# and JavaScript, on local VMs, the Spring Framework on a Web Application Server, Azure Function Apps and Google Cloud Functions. We have looked at emergent standards and best practices, including but not limited to JSON APIs, JSON-LD, SPARQL API, CloudEvents and the FHIR paradigm in healthcare.
  We have used this experience to synthesize a new, revised datatype model that is coherent with the original intent, compatible with the APIs, and known to have at least some degree of practical utility
• (d) We have improved the documentation

After the major revision, we have

• produced a completely revised UML/XMI model, which preserves the original 5 packages
  • "datatypes", for primitive datatypes
  • "id", for identifiers, references and other designators
  • "services", for the "wrappers" used in the API runtime layer
  • "descriptors", to include service manifests used for capability statement and discovery
  • "surrogate", to provide a shape for semantic metadata about Knowledge Resources
• regenerated the derivative models:
  • XSD schemas
  • OpenAPI schemas (JSON schemas in YML format)
  • IDL struct definitions
• revised the API spec documentation, where the changes impacted Chapter 7, from section 7.2.1 to section 7.2.9 excluded
• revised the API specs themselves, updating the operations as follows:
  • KnowledgeAssetRepository
    • replaced all occurrences of return datatypes "CompositeKnowledgeCarrier" with "KnowledgeCarrier",
    • replaced the return type of 'queryKnowledgeAssetGraph', from "Bindings" to "QueryResults"
  • Transrepresentation
    • consolidated all occurrences of return datatypes "Transrepresentator", "Detector", "Validator", "Deserializer" with "KnowledgeProcessingServiceManifest"
    • consolidated all occurrences of return datatypes "TransrepresentationOperator", "DetectionOperator", "ValidationOperator", "DeserializationOperator" with "KnowledgeProcessingOperator"
  • KnowledgeReasoning
    • removed the declaration of the datatype 'Map', undefined and not used
    • replaced "Bindings" with "QueryResults" as the return type of the "askQuery" operation

Attached, find:

• the preview of the revised documentation, scoped to the impacted sections only (due to size limitations)
• the API4KP spec document changelog, which reports the changes to the document with respect to the original document
• the revised UML/XMI model (api4kp.mdzip)
• a ZIP file containing the derived schemas
• a ZIP file containing the UML diagrams for the revised model

Final remark:

The original datatype model proposed a custom way to bind some datatype elements to "ValueSets" - open enumerations derved from Concept Schemes,
in turn derived from specific sub-trees of the API4KP ontologies. This subject has emerged in other specifications being developed - MVF, SCE, PPMN and KPMN to name a few.
This mechanism was overused in the original and revised submissions of API4KP, and the SKOS bound enumerations did not turn out to be completely satisfactory.
Enumerations are usually 'closed', and not all PSM support complex enumerations; while OWL -> SKOS mappings are fairly common, there is not a single canonical approach.
Moreover, trying to enforce a semantic constraint at the schema syntax level is arguably an incoherent approach.

Given these cosiderations, we have decided do abandon the approach altogether, Instead of Enumerations, we have introduced a more generic ContnrolledTerm datatype,
which consists of a label and a URI that can be used to reference semantic entities such as Concepts.
The (semantic) constraints in the schema are not required to use and/or implement the APIs, so this should not be considered a limitation.
Moreover, we have not abandoned the goal, and will propose a different approach, which needs more discussion and is likely to have a dependency on the MVF standard.
This enhancement will be deferred to a later time.

This issue is strictly against the model files and has limited impact on the specification document. The specification document, which is ptc/21-04-04, should be revised to include the MD diagrams without change to the underlying model under this issue, however.

Migration is important to improve the model files and gain functionality, including but not limited to canonical XMI generation for UML 2.5.1. The eclipse implementation in UML Designer uses an older version of UML and the eclipse dialect.

Thus, the artifacts required to resolve this issue include: (1) the revised XMI file, (2) the updated specification document including the revised images, and (3) the corresponding .svg image archive.

Migration of the Eclipse model is insufficient to address the challenges - it needs to be rebuilt entirely

Because of issues uncovered in the underlying representation, rather than addressing this in two steps, namely (1) basic conversion to MagicDraw, which was this issue, and (2) optimize the model for compatibility with planned work to synchronize with IDL (API4KP-1).

The task force determined that rather than perform migration, the model needs to be rebuilt from scratch, which will be done under API4KP-1 and related issues.Thus we will close this issue with no change, and address the requirement under API4KP-1 and related issues with an entirely new model.

Reproducer:
Api spec - KnowledgeAssetRepository :: addCanonicalKnowledgeAssetSurrogate

the body parameter does not specify a content type, which is defaulted to /. Swagger-CodeGenerated clients pass the value to the server, but the server may reject any payload that does not have an explicit content type.
This behavior has been verified with Spring-Web (2.7), but also (independently) with some enterprise firewall rules.

Either way, the spec should be explicit, and the use of content types should be reviewed across the 5 OpenApi documents

The levelTag parameters is incorrectly specified as a body parameter - a role that shuold be reserved to the main operand, the carrier of the artifact to be processed.

The parameter is a coded string, and does not need to be a body parameter