IF Commons GitHub

Subject profiles

0029Draft

0029-subject-profiles · owner if · domain commons · part of 0003-mizan

Subject kinds

FR-001checkpassing

Mizan's ontology MUST hold the kinds of subject as individuals of the code list mz:SubjectKind: mz:LibrarySubject, mz:ServiceSubject (a headless programming interface or event interface), mz:ApplicationSubject (a user interface), mz:IntegrationSubject and mz:PlatformSubject, each with the mz:workKind it is released as, the sections its profile requires (mz:requiresSection), its requirement templates (mz:requirementTemplate), the form of its proofs (mz:proofForm) and the standards it rests on (mz:profileStandard); the key of a kind is its label, in lower case; a library is released as the work kind ifr:Library and each of the others as ifr:Software (0026-works-versioning FR-004).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the ontology holds the five kinds of subject, a library released as ifr:Library and the rest as ifr:Software, each with a proof and templates

Tests: passed: suite/mizan-profiles.test.ts five kinds of subject, each released as a work kind of the IFR vocabulary, with sections,

Cited by: rules, mizan/mizan

FR-002checkpassing

A specification MAY declare the kind of its subject in its head with **Subject:** <kind> (library, service, application, integration or platform, read without regard to case, the first such line counting), the kind is library where it declares none, and IF the kind it declares is not one of the five, THEN the check MUST report mizan/profile-unknown.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the head names the kind and the audience in any case, the first line counting; a kind or an audience that is none of the ontology's is mizan/profile-unknown

Tests: passed: suite/mizan-profiles.test.ts the head names the kind and the audience, in any case, the first line counting; a kind or

Cited by: rules

FR-003checkpassing

A profile MUST give, for its kind, the sections a specification has (a heading of level two or three), at least one requirement template for each section it asks for, in the EARS patterns of 0003-mizan FR-013, and the form of the proof, so that a requirement of the kind is written and proved the same way in every harness.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: each profile that asks for sections has templates, each in an EARS pattern with a keyword

Tests: passed: suite/mizan-profiles.test.ts every section a profile asks for has at least one requirement template in an EARS pattern

The profiles of the kinds

FR-004checkpassing

The profile of a library (mz:LibrarySubject) MUST ask for no section beyond the format of 0003-mizan, and its proof MUST be the verify of the library (0027-commons-libraries): its requirements are proved by tests that cite them.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the profile of a library asks for no section

Tests: passed: suite/mizan-profiles.test.ts each kind asks for the sections its requirement names, and a library for none

FR-005checkpassing

The profile of a service (mz:ServiceSubject) MUST ask for four sections: Contract (an OpenAPI Description of version 3.1 for a request and response interface, an AsyncAPI document for an event interface, and a JSON Schema for each message, each linked to the terms of the typed ontology the message carries), Contract tests (a test of each operation or message against the contract, which proves the requirement that names it), Service level objectives (each stated as an OpenTelemetry metric with its objective and its window) and Quality attributes (the characteristics of ISO/IEC 25010 that matter to the service, each mapped to the proof that holds it).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the profile of a service asks for its contract, contract tests, objectives and quality attributes, and names OpenAPI 3.1, AsyncAPI, JSON Schema, OpenTelemetry and ISO/IEC 25010

Tests: passed: suite/mizan-profiles.test.ts each kind asks for the sections its requirement names, and a library for none

FR-006checkpassing

The profile of an application (mz:ApplicationSubject) MUST ask for three sections: User journeys (each journey a Gherkin scenario that cites the requirements it exercises), Accessibility (the requirements of the Web Content Accessibility Guidelines 2.2 at the conformance level the application claims, each proved by an automated check, with a review row in the register for what a check cannot prove) and Design system (the design system the application conforms to, and the proof that it does).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the profile of an application asks for its journeys, accessibility and design system, and names WCAG 2.2 and Gherkin with a review row for what a check cannot prove

Tests: passed: suite/mizan-profiles.test.ts each kind asks for the sections its requirement names, and a library for none

FR-007checkpassing

The profile of an integration (mz:IntegrationSubject) MUST ask for two sections, Contract and Contract tests, as a service does; the profile of a platform (mz:PlatformSubject) MUST ask for three, Contract (the interfaces and the extension points that others build on), Contract tests and Service level objectives. These two profiles are the first version, to be extended when the first subject of each kind is specified (OQ-1).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the profiles of an integration and of a platform ask for the sections their requirement names

Tests: passed: suite/mizan-profiles.test.ts each kind asks for the sections its requirement names, and a library for none

Audience models

FR-008checkpassing

Mizan's ontology MUST hold the audience models as individuals of the code list mz:AudienceModel: mz:BusinessToBusiness (key b2b) and mz:BusinessToBusinessToConsumer (key b2b2c), each with the sections it requires, its requirement templates, the form of its proofs, the standards it rests on and the laws it cites (mz:profileAuthority); a specification MAY declare its audience in its head with **Audience:** b2b or **Audience:** b2b2c, and where it declares none it is asked for nothing of an audience.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the ontology holds the audience models b2b and b2b2c with their sections, proofs, standards and laws

Tests: passed: suite/mizan-profiles.test.ts b2b asks for five sections and b2b2c for those and three more, citing the laws of consumer

Cited by: rules, mizan/mizan

FR-009checkpassing

The profile of a business-to-business subject MUST ask for five sections: Tenant isolation (what one tenant can never see or change of another's, proved by a test that tries), Service level agreements (what is promised to a tenant and what is owed where it is not kept), Audit trail (what is recorded of each action, by whom, kept how long), Data processing (what personal and tenant data is processed, where and under whose instruction) and Security controls (the controls of SOC 2, ISO/IEC 27001 and NIST SP 800-53 that the subject implements, as 0007-grc states controls and their evidence).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: b2b asks for tenant isolation, service level agreements, audit trail, data processing and security controls, naming SOC 2, ISO/IEC 27001 and NIST SP 800-53

Tests: passed: suite/mizan-profiles.test.ts b2b asks for five sections and b2b2c for those and three more, citing the laws of consumer

FR-010checkpassing

The profile of a business-to-business-to-consumer subject MUST ask for the five sections of a business-to-business subject and three more: Actor roles (the operator, the partner or tenant and the end user, each with the scenarios in Gherkin that say what the role does and may not do), Consumer privacy and consent (what an end user consents to and how it is recorded and withdrawn, citing the laws that apply as mz:Authority individuals, the General Data Protection Regulation and the California Consumer Privacy Act among them) and Data boundaries (what a partner sees of its end users and what an end user sees of the partner, and what neither sees).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: b2b2c asks for the five sections of b2b and for actor roles, consumer privacy and consent and data boundaries, citing the GDPR and the CCPA

Tests: passed: suite/mizan-profiles.test.ts b2b asks for five sections and b2b2c for those and three more, citing the laws of consumer

The check

FR-011checkpassing

The check MUST report each section that the profile of a specification's kind and audience requires and that the specification lacks as mizan/profile-section-missing, once for each specification and section, as a warning held by the baseline of 0003-mizan FR-015; a section is present where the specification has a heading of level two or three that begins with that name, in any case.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: a missing section is found once, a heading of level two or three that begins with its name is present in any case, and the finding is held by a baseline that only shrinks

Tests: passed: suite/mizan-profiles.test.ts each section a profile asks for that a specification lacks is found once, a heading of lev

Cited by: rules

FR-012checkpassing

A specification that declares no kind and no audience MUST have no finding of this check, so that a harness whose specifications declare nothing sees no change; the check MUST run at L1 and above and MUST NOT run at L0 (0028-conformance-levels FR-009).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: a specification that declares nothing, or a library, has no finding; the check runs from L1 and not at L0

Tests: passed: suite/mizan-profiles.test.ts a specification that declares nothing, or a library, has no finding, and the check runs fr

FR-013checkpassing

The profiles MUST cite standards and laws only, by the name and edition the issuer gives, and MUST mark (to verify) a name or an edition that was not checked; a profile MUST NOT name a company, a customer or a product.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: every standard of a profile carries its edition or is marked to verify, and no profile names a company

Tests: passed: suite/mizan-profiles.test.ts every standard of a profile is named with its edition or marked to verify, and no profile

FR-014checkpassing

The ontology MUST hold the General Data Protection Regulation (Regulation (EU) 2016/679) and the California Consumer Privacy Act (California Civil Code section 1798.100 and following) as mz:Authority individuals with their jurisdictions, so that a requirement cites them with Authority: as 0018-standards-first FR-015 asks for a law.

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan-profiles.test.ts: the GDPR and the CCPA are mz:Authority individuals a requirement may cite

Tests: passed: suite/mizan-profiles.test.ts the General Data Protection Regulation and the California Consumer Privacy Act are authori

Cited by: mizan/mizan

Acceptance scenarios

  1. Given a specification that declares **Subject:** service and holds a Contract section only, When the check runs, Then it reports Contract tests, Service level objectives and Quality attributes as missing sections, per FR-005 and FR-011.
  2. Given a specification that declares nothing, When the check runs, Then it has no finding of this check, per FR-002 and FR-012.
  3. Given a specification that declares **Subject:** application and **Audience:** b2b2c, When the check runs, Then it asks for the three sections of an application, the five of a business-to-business subject and the three of a business-to-business-to-consumer one, per FR-006, FR-009, FR-010 and FR-011.
  4. Given **Subject:** gadget, When the check runs, Then it reports mizan/profile-unknown naming the kind, per FR-002.
  5. Given a baseline that holds a missing section and a specification that now has it, When the check runs, Then the line is stale and the check fails until it is deleted, per FR-011.

Out of scope

  • The levels a subject is held to: 0028-conformance-levels.
  • What a particular service or application does: its own specification says so.
  • Checking that a contract is valid OpenAPI, AsyncAPI or JSON Schema, that a journey passes or that a page is accessible: the proof of each requirement is its own test (FR-003); this check reads headings only.

Edge cases

  • A specification with **Subject:** Service in another case: read as service, per FR-002.
  • A specification that declares a kind twice: the first is read, per FR-002.
  • A heading ### Contract tests at level three: present, per FR-011.
  • A heading that only contains the name in a longer title, such as ## Contract tests of the billing queue: present, per FR-011.
  • A specification whose profile section exists only as a sentence in a list: missing, per FR-011.
  • A library at L0: the check does not run, per FR-012.
  • A harness that declares a kind of its own: mizan/profile-unknown; the five kinds are the ontology's, per FR-001 and FR-002.
  • A specification that declares **Audience:** consumer: mizan/profile-unknown names the audience, per FR-008.

Assumptions

  • The five kinds are the ones the work of Intellectual Frontiers needs today; a kind is added to the ontology, with its profile, when a subject needs one.
  • A heading is how a person finds a section: the check reads headings and never the text under them.

Open questions

OQ-1open question

What a profile asks of an integration and of a platform beyond a contract and its tests, to be settled when the first of each is specified.

OQ-2open question

Whether a missing section of a subject at L3 should fail in the gate phase of 0020-ifccm and not only warn, to be settled when the first service is specified.

Key entities

  • Subject kind - library, service, application, integration or platform: what a specification specifies.
  • Audience model - business to business, or business to business to consumer: who the subject is offered to.
  • Profile - the sections, the requirement templates, the form of proof and the standards of a kind or an audience.

Success criteria

SC-001success criterion

A specification that declares service and lacks the profile's sections is told so by the check, and one that has them is not.

SC-002success criterion

A harness whose specifications declare nothing has the same findings as before the profiles existed.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

rules, mizan/mizan, The harness of Mizan, Conformance levels

Titles, headings, exports, tables, columns and requirements. Esc closes.