kontextual-engine/docs/cmis-compliance-assessment.md

# CMIS Compliance Assessment

Date: 2026-05-07

Status: Browser Binding subset implemented with conservative CMIS capability
flags and explicit unsupported diagnostics.

## Reference Standard

Target CMIS version: OASIS Content Management Interoperability Services
Version 1.1, OASIS Standard, approved 23 May 2013, including approved errata
where applicable.

CMIS defines a domain model plus Web Services, AtomPub, and Browser JSON
bindings for one or more content repositories. The standard explicitly allows a
CMIS endpoint to expose more than one repository and does not require every
underlying content-management feature to be represented through CMIS.

## Reusable Validation Foundation

Primary reusable validation candidate: Apache Chemistry OpenCMIS TCK and CMIS
Workbench.

OpenCMIS provides client libraries, server frameworks, development tools,
InMemory/FileShare reference repositories, and TCK artifacts. The project pages
now indicate the project is retired, so we should treat OpenCMIS as a legacy
compatibility validation tool rather than a moving dependency. The Maven
artifact `org.apache.chemistry.opencmis:chemistry-opencmis-test-tck:1.1.0`
remains available and should be used as the first external conformance harness.

Practical strategy:

- Build local, deterministic example fixtures grouped by CMIS service
  capability.
- Build internal contract tests that validate our mapper and profile behavior
  without Java tooling.
- Add an optional external TCK harness that can run OpenCMIS TCK against a
  running CMIS access point when Java/Maven are available.
- Keep TCK execution optional in the default Python suite to avoid turning the
  engine into a Java project.

## Capability Assessment

| CMIS capability | Current engine availability | Gap | Demand |
| --- | --- | --- | --- |
| Repository service | Implemented. | Repository info includes CMIS 1.1 identity, complete conservative optional capability flags, repository features, and unsupported feature diagnostics. | Low |
| Type definitions | Implemented subset. | Base type projections exist; type mutability, CMIS versioning, folder ACL control, and non-document querying are explicitly not advertised. | Low |
| Navigation service | Implemented subset. | `getChildren` and projected parents are supported. `getDescendants`, `getFolderTree`, mutating multifiling, and unfiling are explicitly flagged unsupported. | Low unless full folder tree is required |
| Object service read | Implemented subset. | Object envelopes, allowable actions, content stream descriptors, content stream properties, visibility redaction, and relationship IDs are covered. | Low |
| Object service write | Governed subset. | `createDocument`, custom metadata updates, `setContentStream`, and delete-request lifecycle transition are supported by authoring profiles. Unsupported standard property updates now fail with diagnostics. | Medium |
| Content streams | Implemented subset. | Descriptor and byte-stream routes exist; `setContentStream` and whole-object `appendContentStream` write through deduplicating blob storage, while `deleteContentStream` tombstones the CMIS projection. Chunk-level append composition remains deferred. | Low |
| Versioning | Projection only. | Latest-version properties can be projected from engine versions, but CMIS checkout/PWC/all-versions services are not advertised. | Low if unsupported remains acceptable |
| Discovery/query | Implemented bounded subset. | `SELECT *` document queries support equality, `LIKE`, `IN`, `AND`, paging, and common CMIS property ordering. Joins, full text, nested predicates, arbitrary projection lists, and custom-property ordering are flagged unsupported. | Medium |
| Relationships | Implemented subset. | Relationship object projections, source filters, target filters, either-direction filters, provenance, confidence, and profile-gated visibility are covered. | Low |
| ACL service | Discover only. | ACL projection is supported with stable principal/permission vocabulary, direct/inherited markers, and policy authority metadata; `applyACL` returns an unimplemented diagnostic. | Low |
| Policy service | Unsupported. | `applyPolicy`/`removePolicy` are explicitly unsupported; engine policy remains native, not CMIS policy objects. | Low |
| Change log | Implemented subset. | Audit-backed object-id change entries and paging are supported; full property-level change details are not advertised. | Low |
| Multi-filing/unfiling | Projection only. | Multiple virtual parents are exposed as a Kontextual repository feature, while CMIS `capabilityMultifiling` and unfiling stay false. | Low |
| Renditions | Unsupported. | Capability is `none`; derived representations are not exposed as CMIS rendition streams. | Low |
| Retention and hold | Unsupported. | Not advertised; left as native governance metadata until a real integration requires CMIS legal-hold semantics. | Low |
| Bulk update | Profile-scoped subset. | `bulkUpdateProperties` is available for the TCK compatibility profile through existing governed property updates and change-token handling; it remains narrow and is not enabled on normal authoring profiles. | Low |
| Browser JSON binding | FastAPI JSON service already exists. | Need CMIS Browser Binding routes, selectors/actions, multipart/content stream behavior. | High |
| AtomPub binding | No AtomPub/XML binding. | Need XML/Atom feed generation and protocol semantics. | Very High |
| Web Services binding | No SOAP stack. | Need WSDL/SOAP implementation. | Very High |

## Recommended Compliance Profile Strategy

Maintain a constrained CMIS 1.1 Browser Binding profile:

- Repository, type, object read, content stream read, query subset,
  relationships, change log, and navigation over a synthetic root/folder
  projection.
- Explicitly unsupported or read-only: AtomPub, Web Services, descendants/tree,
  full ACL mutation, retention/hold, mutating multifiling/unfiling, PWC/versioning
  services, renditions, custom-property ordering, broad bulk-update exposure,
  and full CMIS SQL joins.

Then expand by profile:

- `readonly-browser`: safe read-only repository and content access.
- `governed-authoring`: selected object creation/update/content stream changes
  through engine policy and audit.
- `admin-export`: broad export and governance inspection, restricted to
  service accounts.
- `compat-tck`: profile tuned to pass a selected OpenCMIS TCK capability subset.

## Risk Summary

The engine has a sound Browser Binding subset so long as clients trust the
advertised capabilities instead of assuming broad ECM behavior. The remaining
hard parts are optional CMIS semantics that we intentionally do not advertise:
folder tree/descendant services, mutating filing services, PWC/versioning
services, broad query grammar, ACL mutation, renditions, retention/hold, and
legacy bindings.

Best estimate:

- Internal mapper and examples: moderate.
- Browser Binding MVP profile: medium-high.
- TCK subset harness: medium.
- Broad CMIS 1.1 Browser compliance: high.
- AtomPub and Web Services compliance: very high and probably not justified
  until a real client demands those bindings.