Files

tegwick 1ed7198ce3 Initial seeding of models, standards

2026-05-23 00:55:01 +02:00

26 KiB

Raw Permalink Blame History

Product Requirements Document: InfoTechCanon

Document Status: Draft 1
Product Name: InfoTechCanon
Working Repository Name: infotech-canon
Primary Product Type: Markdown-first standards, knowledge, and interoperability framework
Date: 2026-05-22
Owner: Bernd Worsch

1. Definition

A Product Requirements Document (PRD) is a structured document that defines the intended purpose, users, value proposition, scope, requirements, constraints, risks, and success criteria for a product or product-like system.

It explains what should be built and why, without prescribing all implementation details. A PRD serves as a shared reference for stakeholders, designers, developers, architects, reviewers, and agents involved in planning, implementation, validation, and evolution of the product.

2. Context

The InfoTechCanon is intended to become an evolving reference system for building interoperable information-processing systems.

The user is developing multiple tools, repositories, standards, and platform components around markdown-first knowledge management, agentic software development, DevSecOps, IT landscape modeling, governance, access control, task management, tagging, and information processing. These efforts require a shared semantic foundation to reduce contradiction, overlap, and integration friction while preserving adaptability and extensibility.

Recent work includes the first release candidate of a canonical IT landscape model, currently evolving toward the InfoTechCanonLandscapeModel. The user now wants to refactor this and related standards into a broader, interconnected, orthogonal standards system called InfoTechCanon.

The InfoTechCanon should not merely be a static collection of documents. It should become a versioned, markdown-first, machine-readable, human-usable, agent-retrievable body of knowledge that can guide system design and integration across a growing ecosystem of tools and services.

3. Product Vision

InfoTechCanon provides an evolving semantic reference system for building interoperable, adaptable, and extensible information-processing systems.

It enables standards, models, concepts, patterns, profiles, mappings, and assimilation processes to evolve coherently while remaining useful for humans, agents, and software tools.

The InfoTechCanon should serve as a practical foundation for:

designing compatible subsystems,
reducing semantic drift across repositories,
integrating tools and services through declared semantic contracts,
mapping internal concepts to external standards and regulations,
assimilating new bodies of knowledge,
enabling efficient retrieval and reuse by agents and humans,
and guiding the construction of markdown-based infospaces and knowledge-processing systems.

4. Product Purpose

The purpose of InfoTechCanon is to provide a canonical reference layer for information technology and information-processing systems.

It should allow the user and future collaborators to answer questions such as:

What does this concept mean in our system landscape?
Which standard owns this concept?
Which external standards or regulations does it map to?
Which subsystem produces or consumes this concept?
Which patterns describe how this concept is used in practice?
Which profiles constrain this concept for a specific implementation context?
What happens when a new external standard, regulation, product model, or body of knowledge appears?
How can agents retrieve the right knowledge efficiently and use it without inventing contradictory models?

5. Primary Utility

The primary utility of InfoTechCanon is to turn integration by interpretation into integration by declared semantic contract.

Instead of each repository, subsystem, or agent inventing its own terminology and assumptions, InfoTechCanon provides:

stable canonical concepts,
explicit concept ownership,
standard structures,
reusable pattern languages,
application profiles,
mapping artifacts,
assimilation workflows,
retrieval-optimized markdown infospaces,
and conformance rules.

This enables systems to “snap together” more easily while still allowing the standards to evolve.

6. Intended Users

6.1 Primary Users

System Architect

Uses InfoTechCanon to design interoperable subsystems, clarify domain boundaries, and reduce overlap between standards, services, repositories, and models.

Repository Maintainer

Uses InfoTechCanon to declare which concepts a repository owns, produces, consumes, or implements.

Agentic Coding Assistant

Retrieves relevant standards, terms, profiles, and patterns to generate compatible code, documentation, schemas, mappings, and integration artifacts.

Standards Author

Creates and refactors InfoTechCanon standards, concept definitions, mapping files, profiles, and pattern-language documents.

Platform Builder

Uses InfoTechCanon as the semantic reference layer for services such as markitect-tool, kontextual-engine, shard-wiki, llm-connect, phase-memory, user-engine, landscape tools, and task-management tools.

6.2 Secondary Users

Governance / Compliance Reviewer

Uses mappings and assimilation reports to understand how internal concepts relate to external regulations, frameworks, and audit requirements.

Product Owner

Uses the canon to align product requirements, service boundaries, task models, and system responsibilities.

Developer

Uses profiles, interface cards, and validation rules to implement systems that remain compatible with the broader ecosystem.

Knowledge Curator

Maintains the markdown infospace, indexes, concept pages, backlinks, and retrieval structures.

7. Core Product Principles

7.1 Canonical Autonomy

InfoTechCanon may map to external standards, but it must not be subordinated to them.

External standards, regulations, and product models influence the canon through mappings and assimilation, not by directly defining internal semantics.

7.2 Orthogonality

Each standard should own a distinct set of primary concerns. Standards may import concepts from other standards but should not redefine them.

A concept may be used by many standards but should have exactly one canonical owner.

7.3 Network Before Tree

Hierarchy is useful for abstraction and navigation, but InfoTechCanon is fundamentally an interconnected network of terms, standards, patterns, profiles, mappings, and relationships.

7.4 Pattern-Language Orientation

The canon should not only define concepts. It should also provide practical reusable patterns inspired by pattern-language thinking.

A pattern describes a recurring problem, relevant forces, a reusable solution, consequences, related concepts, and implementation guidance.

7.5 Markdown-First, Machine-Readable

Canon artifacts should be written as human-readable Markdown with structured metadata that enables indexing, validation, retrieval, transformation, and agent use.

7.6 Assimilation Instead of Blind Adoption

When a new standard, regulation, model, or body of knowledge appears, InfoTechCanon should run an assimilation process to extract concepts, compare them to internal concepts, identify gaps and conflicts, propose changes, and publish mappings.

7.7 Retrieval as a First-Class Requirement

The canon must be efficiently retrievable and reusable by both humans and agents.

Documentation, metadata, summaries, indexes, stable identifiers, front matter, and chunking strategies should be designed accordingly.

7.8 Evolution With Traceability

The canon must evolve without losing provenance, compatibility information, or historical reasoning.

Changes should preserve why a concept exists, what influenced it, what it replaced, and how it maps externally.

8. Product Scope

8.1 In Scope

The InfoTechCanon product includes:

a core meta-standard for defining all other standards,
canonical concept and relationship models,
standard document structures,
concept ownership rules,
mapping mechanisms to external standards and regulations,
assimilation workflow definitions,
pattern-language structures,
application profile structures,
retrieval and reuse conventions,
machine-readable metadata schemas,
repository layout conventions,
conformance levels,
validation rules,
and initial domain standards.

Initial domain standards may include:

InfoTechCanonCore,
InfoTechCanonLandscapeModel,
InfoTechCanonOrganizationModel,
InfoTechCanonGovernanceModel,
InfoTechCanonTaskModel,
InfoTechCanonTaggingStandard,
InfoTechCanonAccessControlModel,
InfoTechCanonPatternLanguage.

8.2 Out of Scope

The initial product does not include:

a complete implementation of every domain standard,
full legal or regulatory compliance certification,
a replacement for external standards such as ArchiMate, CSDM, ITIL, PMBOK, ISO, NIST, YANG, SPDX, or CycloneDX,
a mandatory enterprise-wide data model that all systems must implement fully,
a graphical modeling tool,
a complete ontology editor,
a fully automated standards governance board,
or a guarantee that all external standards can be mapped without ambiguity.

9. Product Architecture

9.1 Conceptual Product Structure

InfoTechCanon should consist of four major layers:

InfoTechCanon
├── Canon Core
├── Domain Standards
├── Pattern Languages
└── Application Profiles

9.2 Canon Core

The Canon Core defines the rules for the entire standards system.

It should include:

canon artifact model,
concept model,
relationship model,
concept ownership model,
standard structure,
mapping model,
assimilation model,
pattern model,
profile model,
retrieval model,
provenance model,
versioning model,
conformance model,
and repository layout conventions.

9.3 Domain Standards

Domain standards define canonical concepts for sufficiently independent domains.

Initial candidates:

InfoTechCanonCore
InfoTechCanonLandscapeModel
InfoTechCanonOrganizationModel
InfoTechCanonGovernanceModel
InfoTechCanonTaskModel
InfoTechCanonTaggingStandard
InfoTechCanonAccessControlModel
InfoTechCanonServiceModel
InfoTechCanonSoftwareModel
InfoTechCanonDevSecOpsModel
InfoTechCanonNetworkModel
InfoTechCanonSecurityModel
InfoTechCanonObservabilityModel
InfoTechCanonDataModel

Not all of these need to be created immediately. Some may begin as sections, profiles, or extraction candidates.

9.4 Pattern Languages

Pattern languages describe recurring practical solutions using canonical concepts.

Example pattern families:

landscape patterns,
governance patterns,
task patterns,
tagging patterns,
integration patterns,
security patterns,
DevSecOps patterns,
retrieval patterns,
assimilation patterns.

9.5 Application Profiles

Application profiles constrain the canon for concrete use cases.

Examples:

KubernetesLandscapeProfile,
GitHubIssuesTaskTaggingProfile,
ServiceNowCSDMMappingProfile,
NetBoxNetworkSourceOfTruthProfile,
BackstageSoftwareCatalogProfile,
SmallSaaSDevSecOpsProfile,
EnterpriseSaaSComplianceProfile.

10. Functional Requirements

10.1 Canon Artifact Management

REQ-CANON-001: Canon Artifact Types

The system shall define canonical artifact types including:

Standard,
Concept,
Relationship,
Pattern,
Profile,
Mapping,
Assimilation Report,
Conformance Rule,
Validation Rule,
Interface Card,
Example,
Decision Record.

REQ-CANON-002: Stable Identifiers

Each canon artifact shall have a stable identifier.

Identifiers should be suitable for human reference, machine processing, linking, and retrieval.

REQ-CANON-003: Structured Metadata

Each canon artifact shall support structured metadata, preferably through Markdown front matter.

Metadata should include at least:

id,
title,
artifact type,
status,
version,
canonical owner,
imported standards,
related artifacts,
source references,
provenance,
and lifecycle state.

10.2 Concept Ownership

REQ-CONCEPT-001: Single Canonical Owner

Each canonical concept shall have exactly one owning standard.

REQ-CONCEPT-002: Concept Reuse Through Imports

Standards shall reuse concepts from other standards by import or reference, not by redefinition.

REQ-CONCEPT-003: Concept Status

Each concept shall have a lifecycle status.

Recommended statuses:

proposed,
experimental,
candidate,
canonical,
deprecated,
retired.

REQ-CONCEPT-004: Concept Disambiguation

Concept definitions should include “do not confuse with” notes where ambiguity is likely.

10.3 Mapping

REQ-MAP-001: External Mapping Support

The canon shall support explicit mappings between InfoTechCanon concepts and external standards, regulations, product models, frameworks, and bodies of knowledge.

REQ-MAP-002: Mapping Types

Mappings shall support at least the following mapping types:

exactMatch,
closeMatch,
broadMatch,
narrowMatch,
relatedMatch,
conflictMatch,
gapMatch,
derivedFrom,
regulatoryReference.

REQ-MAP-003: Scoped Mappings

Each mapping shall declare its scope and known limits.

REQ-MAP-004: Versioned Mappings

Each mapping to an external body of knowledge shall specify the target body and target version where known.

REQ-MAP-005: Mapping Rationale

Each non-trivial mapping shall include a rationale explaining why the mapping exists and how it should be interpreted.

REQ-MAP-006: Mapping Lifecycle

Mappings shall have lifecycle statuses such as:

proposed,
reviewed,
candidate,
accepted,
deprecated,
superseded,
rejected.

10.4 Assimilation

REQ-ASSIM-001: Assimilation Candidate

The canon shall support an assimilation candidate artifact for external bodies of knowledge.

REQ-ASSIM-002: Assimilation Process

The assimilation process shall include:

intake,
scoping,
concept extraction,
concept comparison,
gap and conflict analysis,
canon impact proposal,
mapping and publication.

REQ-ASSIM-003: Assimilation Outputs

Each completed assimilation should produce:

assimilation report,
source summary,
extracted concepts,
comparison matrix,
mappings,
proposed changes,
open questions,
deferred items.

REQ-ASSIM-004: Assimilation Does Not Automatically Mutate Canon

Assimilation shall produce change proposals, mappings, and recommendations. Canon changes require explicit acceptance.

REQ-ASSIM-005: Gap and Conflict Capture

Assimilation shall explicitly capture gaps, conflicts, overlaps, ambiguities, and potential refactoring opportunities.

10.5 Pattern Language

REQ-PATTERN-001: Pattern Format

The canon shall define a reusable pattern format including:

name,
aliases,
context,
problem,
forces,
solution,
resulting context,
used concepts,
related patterns,
known variants,
failure modes,
examples,
implementation notes.

REQ-PATTERN-002: Pattern References

Standards and profiles shall be able to reference patterns.

REQ-PATTERN-003: Pattern Families

Patterns should be organized into pattern families such as governance, integration, task, landscape, security, and DevSecOps patterns.

10.6 Application Profiles

REQ-PROFILE-001: Profile Definition

The canon shall support application profiles that constrain canon concepts for specific implementation contexts.

REQ-PROFILE-002: Profile Content

A profile shall define:

used standards,
included concepts,
required relationships,
required metadata,
constraints,
validation rules,
examples,
supported integrations,
known deviations.

REQ-PROFILE-003: Profile Conformance

A subsystem may declare conformance to a profile.

10.7 Interface Cards

REQ-IFC-001: Canon Interface Card

The canon shall define a Canon Interface Card format for subsystems.

A Canon Interface Card shall describe:

subsystem name,
implemented standards,
implemented profiles,
owned concepts,
produced concepts,
consumed concepts,
accepted relationships,
emitted events,
required identifiers,
mapping rules,
validation rules,
known deviations.

REQ-IFC-002: Subsystem Integration

Subsystems should use Canon Interface Cards to declare how they snap into the larger InfoTechCanon ecosystem.

10.8 Retrieval and Reuse

REQ-RET-001: Markdown-First Retrieval

The canon shall be stored in Markdown files that are structured for both human readability and machine retrieval.

REQ-RET-002: Agent Briefs

Each standard should provide an agent-oriented brief containing:

purpose,
scope,
owned concepts,
imported concepts,
canonical patterns,
do / do not guidance,
common mistakes,
minimal examples.

REQ-RET-003: Indexes

The canon shall provide indexes by:

standard,
concept,
pattern,
profile,
mapping,
external standard,
status,
domain,
use path.

REQ-RET-004: Chunking Support

Markdown artifacts should be written in a way that supports reliable retrieval chunks with stable headings and identifiers.

REQ-RET-005: Machine-Readable Exports

The canon should support machine-readable exports such as YAML, JSON, JSON-LD, RDF, or graph representations.

10.9 Provenance

REQ-PROV-001: Provenance Metadata

Each significant canon artifact shall support provenance metadata.

REQ-PROV-002: Source Traceability

The canon shall record which sources, assimilations, decisions, or prior concepts influenced a concept, mapping, profile, or pattern.

REQ-PROV-003: Change Traceability

The canon shall record supersession, deprecation, replacement, and compatibility information.

10.10 Versioning and Compatibility

REQ-VER-001: Versioned Standards

Each standard shall have a version and status.

Recommended statuses:

idea,
draft,
candidate,
release-candidate,
adopted,
stable,
deprecated,
retired.

REQ-VER-002: Change Classification

Changes shall be classified as:

patch,
minor,
major,
fork.

REQ-VER-003: Compatibility Notes

Major semantic changes shall include compatibility and migration notes.

11. Non-Functional Requirements

11.1 Usability

The canon must remain readable and useful to humans without requiring specialized ontology tooling.

11.2 Agent Usability

The canon must provide concise, structured, retrievable artifacts that help agents produce compatible outputs.

11.3 Extensibility

The canon must allow new standards, profiles, mappings, and patterns to be added without destabilizing existing work.

11.4 Traceability

The canon must preserve provenance, source references, change history, and mapping rationale.

11.5 Modularity

Standards should be modular and orthogonal. Subsystems should be able to implement only relevant profiles.

11.6 Interoperability

The canon should support integration with markdown infospaces, graph tools, validation tools, documentation generators, agentic coding systems, and service APIs.

11.7 Low Friction

The initial implementation should be simple enough to maintain manually in Markdown while enabling progressive automation.

12. Suggested Repository Structure

infotech-canon/
  README.md
  INTENT.md
  SCOPE.md
  canon.yaml

  core/
    InfoTechCanonCore.md
    terms/
    relations/
    patterns/
    profiles/
    conformance/

  standards/
    organization/
    governance/
    landscape/
    task/
    tagging/
    access-control/
    security/
    devsecops/
    network/
    observability/
    data/

  patterns/
    integration/
    governance/
    landscape/
    task/
    security/
    retrieval/

  profiles/
    github-issues-task-profile/
    kubernetes-landscape-profile/
    service-now-csdm-profile/
    netbox-network-profile/
    backstage-software-catalog-profile/

  mappings/
    external/
      archimate/
      csdm/
      nist-csf/
      itil/
      pmbok/
      yang/
      backstage/
      spdx/
      cyclonedx/

  assimilation/
    inbox/
    active/
    completed/

  schemas/
    concept.schema.yaml
    standard.schema.yaml
    mapping.schema.yaml
    pattern.schema.yaml
    profile.schema.yaml
    assimilation.schema.yaml
    interface-card.schema.yaml

  views/
    by-domain.md
    by-concept.md
    by-pattern.md
    by-profile.md
    by-external-standard.md
    by-status.md
    use-paths.md

  agent/
    briefs/
    retrieval-index.md
    common-mistakes.md

13. Success Criteria

13.1 Initial Success Criteria

The first release is successful if:

InfoTechCanonCore exists as a coherent standard.
InfoTechCanonLandscapeModel is refactored to import core concepts.
At least one mapping file exists for an external standard.
At least one assimilation report exists.
At least one application profile exists.
At least one Canon Interface Card exists.
The repository can be navigated by humans through Markdown.
The repository can be indexed and retrieved by agents.
Concept ownership can be validated manually or by script.

13.2 Medium-Term Success Criteria

The project is successful at the next maturity stage if:

multiple repositories declare implemented standards and profiles,
agents use the canon to generate more consistent artifacts,
new external standards can be assimilated through a repeatable process,
mappings are versioned and maintained,
domain standards remain orthogonal with limited overlap,
and the canon becomes a practical reference point for system design.

13.3 Long-Term Success Criteria

The project is successful long-term if:

InfoTechCanon becomes the semantic substrate for the user’s information-processing systems,
markdown infobase tools and services use it as a core driving use case,
subsystems can be integrated through declared semantic contracts,
standards evolve without uncontrolled contradiction,
and humans and agents can reliably retrieve, reuse, and extend the body of knowledge.

14. Risks and Mitigations

14.1 Risk: Over-Abstraction

The canon may become too abstract to guide real implementation.

Mitigation: Require examples, profiles, patterns, and interface cards for important concepts.

14.2 Risk: Excessive Scope

The canon may attempt to cover too many domains at once.

Mitigation: Start with InfoTechCanonCore, LandscapeModel, OrganizationModel, GovernanceModel, TaskModel, and TaggingStandard. Treat additional domains as candidates.

14.3 Risk: Semantic Drift

Different standards may redefine similar concepts.

Mitigation: Enforce single canonical owner per concept and require imports for reuse.

14.4 Risk: External Standard Pressure

External standards may distort internal concepts.

Mitigation: Use mappings and assimilation reports instead of direct adoption.

14.5 Risk: Poor Retrieval Quality

Agents may retrieve irrelevant or outdated content.

Mitigation: Use stable IDs, front matter, summaries, indexes, lifecycle states, and agent briefs.

14.6 Risk: Manual Maintenance Burden

Maintaining mappings, concepts, profiles, and indexes may become expensive.

Mitigation: Start markdown-first, then progressively automate validation, index generation, mapping checks, and retrieval exports.

14.7 Risk: Contradictions Between Standards

As standards grow, contradictions may emerge.

Mitigation: Add overlap reviews, concept ownership checks, conflict reports, and periodic canon refactoring cycles.

15. Open Questions

Should InfoTechCanonCore be a single document initially or split immediately into core modules?
Which external standard should be assimilated first as a test case?
Should the first application profile target GitHub Issues, Kubernetes, ServiceNow CSDM, or a user-owned repository?
Which schema language should be used first for machine-readable artifacts: YAML Schema, JSON Schema, JSON-LD, RDF/OWL, or a simpler custom convention?
Should pattern documents live globally or inside domain standards first?
How strict should conformance validation be in the first release?
Should InfoTechCanon use namespace prefixes such as itc-core, itc-landscape, itc-task, and itc-gov from the beginning?

16. Initial Roadmap

Phase 1: Foundation

Create InfoTechCanonCore.md.
Define artifact types, concept ownership, mapping model, assimilation model, profile model, pattern format, retrieval model, and versioning.
Create initial repository structure.
Define naming and identifier conventions.

Phase 2: Refactor Existing Work

Rename and refactor CILM_Standard_RC1.md into InfoTechCanonLandscapeModel_RC1.md.
Extract organization and governance assumptions into candidate standards.
Create initial imports between standards.

Phase 3: First Mapping and Assimilation

Select one external standard for assimilation.
Produce an assimilation report.
Produce mappings.
Propose canon changes.

Phase 4: First Application Profile

Define a concrete profile, such as GitHubIssuesTaskTaggingProfile or KubernetesLandscapeProfile.
Add validation rules.
Add example artifacts.

Phase 5: Agent and Tool Integration

Create agent briefs.
Create machine-readable indexes.
Integrate with markdown infobase tooling.
Test retrieval with real agentic coding and documentation workflows.

Phase 6: Subsystem Integration

Define Canon Interface Cards for selected repositories or services.
Use the canon to guide integration between tools such as markitect-tool, kontextual-engine, shard-wiki, user-engine, landscape tooling, and task tooling.

17. Acceptance Criteria for First Deliverable

The first deliverable should be accepted if it includes:

a clear InfoTechCanon product definition,
a coherent product scope,
a description of the canon architecture,
mapping requirements,
assimilation requirements,
retrieval requirements,
pattern and profile requirements,
initial repository structure,
risks and mitigations,
open questions,
and an actionable roadmap.

18. Summary

InfoTechCanon is intended to become an evolving, markdown-first, machine-readable, human-usable reference system for interoperable information-processing systems.

Its distinctive mechanisms are:

Mapping keeps the canon externally legible.
Assimilation keeps the canon intellectually alive.
Retrieval keeps the canon operationally useful.
Patterns keep the canon practical.
Profiles keep the canon implementable.
Concept ownership keeps the canon orthogonal.

The product should begin with a strong core meta-standard and then grow through domain standards, mappings, assimilation reports, profiles, patterns, and subsystem interface cards.

The ultimate goal is to make InfoTechCanon a living semantic substrate for building adaptable systems that remain compatible without becoming rigid.

26 KiB Raw Permalink Blame History Unescape Escape