Skip to main content

ACF Governed Connector Schema v1

1. Purpose​

The ACF Governed Connector Schema v1 defines the common machine-readable governance model for all ZAYAZ accounting, ERP and accounting-data-standard connectors.

It was derived from the connector architecture work for:

  • SIE;
  • Xledger;
  • Tripletex;
  • Oracle NetSuite;
  • Fortnox;
  • Visma e-conomic;
  • SAP;
  • Microsoft Dynamics 365 Business Central; and
  • QuickBooks Online.

The purpose is not to force those systems into identical technical implementations.

The purpose is to make their differences expressible through one governed model.

The core principle is:

Provider-specific transport and semantics remain visible, while identity, capability, provenance, synchronization, evidence and ESG interpretation are governed consistently by ZAYAZ.

2. Schema family​

ACF v1 is deliberately a schema family rather than one oversized object.

zayaz.acf.connector.v1
        │
        ├── zayaz.acf.connection-profile.v1
        ├── zayaz.acf.capability.v1
        ├── zayaz.acf.source-interface.v1
        ├── zayaz.acf.source-identity.v1
        ├── zayaz.acf.scope-identity.v1
        ├── zayaz.acf.identity-resolution.v1
        ├── zayaz.acf.semantic-resolution.v1
        ├── zayaz.acf.mapping.v1
        ├── zayaz.acf.sync-state.v1
        ├── zayaz.acf.evidence-relation.v1
        └── zayaz.acf.data-quality.v1

The governed connector registry is:

schemas/acf/acf.connector.registry.json

3. Static connector definition versus customer connection profile​

A connector definition and a live customer connection are different governed objects.

Connector definition​

Answers:

What can this provider and ZAYAZ connector architecture support?

Examples:

ACF-SAP
ACF-FORTNOX
ACF-QUICKBOOKS

A connector definition includes:

  • provider and product identity;
  • deployment profiles;
  • supported authentication models;
  • source interfaces;
  • known source domains;
  • provider capabilities;
  • change-capture mechanisms;
  • synchronization patterns;
  • evidence capabilities;
  • data-quality potential;
  • security requirements; and
  • governance.

Customer connection profile​

Answers:

What can this specific customer connection actually do now?

A connection profile can depend on:

  • provider tenant;
  • environment;
  • company / realm / company code;
  • source-system release;
  • product plan or licence;
  • enabled modules;
  • communication scenario;
  • permissions;
  • OAuth consent;
  • available API version;
  • customer extensions;
  • webhook/event availability;
  • mappings; and
  • source configuration.

The runtime profile is therefore authoritative for effective capability.

4. Capability is resolved, not Boolean​

ACF v1 does not treat this as sufficient:

supported: true

Effective capability is resolved across several dimensions:

provider support
      ×
connector support
      ×
customer entitlement
      ×
customer configuration
      ×
authorization
      ×
source mapping
      ×
ZAYAZ policy
      ↓
effective capability

This supports cases such as:

  • Fortnox scope plus product licence;
  • e-conomic application role plus customer module;
  • SAP released API plus communication arrangement;
  • Business Central Entra permission plus BC permission set;
  • QuickBooks API entity plus product-plan feature;
  • NetSuite feature plus account-specific schema; and
  • Xledger account-specific discovered fields.

5. Source context model​

Different systems use different identity hierarchies.

ACF normalizes them into these source-context levels:

provider_tenant
      ↓
environment
      ↓
organization
      ↓
organizational_unit
      ↓
project
      ↓
facility

Not every connector uses every level.

Examples:

QuickBooks
realmId → organization
Business Central
Entra tenant → environment → company
SAP
system → client → company code → cost center / plant / WBS

The source context remains provider-native until it is explicitly resolved to a governed ZAYAZ scope identity.

6. ZAYAZ scope identity family​

ACF v1 introduces three governed identity classes.

ECO — Eco Organization​

identity_type: organization
id_class: ECO

ECO identifies a governed organization, legal entity, reporting entity or other organization-level scope.

A provider company, subsidiary or company code is a candidate for ECO resolution. It is not automatically proof of legal identity.

EBU — Eco Business Unit​

identity_type: organizational_unit
id_class: EBU

EBU identifies a non-legal internal organizational scope such as:

  • business unit;
  • department;
  • cost center;
  • profit center;
  • operating unit; or
  • comparable management scope.

An EBU may receive accounting activity, evidence, targets, budgets, calculations and ESG attribution without being represented as an independent company.

EBP — Eco Business Project​

identity_type: project
id_class: EBP

EBP identifies a governed project, programme, engagement or investment scope.

Examples include:

  • construction project;
  • infrastructure project;
  • consulting engagement;
  • R&D programme;
  • product launch;
  • plant expansion; and
  • customer implementation project.

EBP allows accounting and activity data from systems such as SAP WBS, Business Central Projects, Fortnox Projects, Tripletex Projects and e-conomic Projects to resolve to a common project identity.

7. Scope identity is not a hierarchy encoded in the ID​

Scope IDs are stable identities.

They do not encode parent ownership.

Preferred:

ECO-NOR-000123
EBU-NOR-000041
EBP-NOR-000317

Avoid:

ECO-NOR-000123-BU-04-PROJ-008

Ownership, participation and hierarchy are versioned relationships.

Example:

relationships:
  - type: owned_by
    target_scope_id: ECO-NOR-000123
    effective:
      from: 2026-01-01
      to: null

This allows restructuring without changing identity.

8. EBU and EBP do not automatically create additive inventories​

An organizational-unit or project result may already be contained inside its parent organization's inventory.

For example:

ECO-NOR-000123 = 1,000 tCO2e

EBU-NOR-000041 = 600 tCO2e
EBU-NOR-000042 = 400 tCO2e

The group total remains:

1,000 tCO2e

not:

2,000 tCO2e

Every scope identity therefore carries an inventory role and consolidation behavior.

Typical attributed EBU:

inventory_role:
  type: attributed
  consolidation_behavior: included_in_parent
  additive_to_parent: false

Projects may use governed project allocation rather than automatic additive consolidation.

9. Cross-company projects​

An EBP can span several ECO identities.

Example:

                EBP-EUR-000812
                Project X
                    │
        ┌───────────┼───────────┐
        │           │           │
    ECO-NOR      ECO-DNK     ECO-DEU

Project participation, ownership and allocation are relationships rather than identifier structure.

This supports project footprinting without corrupting organization-level GHG consolidation.

10. Future product identity​

ACF v1 intentionally does not define a product or product-unit identity class.

The schema reserves room for future extension because product identity will require additional governance around:

  • product versus product-unit identity;
  • lot and serial identity;
  • bill-of-material relationships;
  • allocation rules;
  • upstream/downstream chain of custody;
  • product lifecycle;
  • Digital Product Passport relationships; and
  • product-footprint versioning.

A future product-unit concept must therefore be designed explicitly rather than being added casually to ECO/EBU/EBP.

11. Source identity versus scope identity​

These concepts must never be collapsed.

Source identity​

Answers:

Which record in which source system produced this evidence?

Example:

provider: quickbooks
context:
  environment: production
  organization: "9341458293021"
object:
  type: Bill
  id: "245"
revision:
  provider_token: "2"

Scope identity​

Answers:

Which governed ZAYAZ organization/unit/project does this activity belong to?

Example:

organization: ECO-NOR-000123
organizational_unit: EBU-NOR-000041
project: EBP-NOR-000317

Identity resolution creates the governed relationship between the two.

12. Source revision versus synchronization cursor​

ACF v1 distinguishes three concepts.

SOURCE IDENTITY
Which source object?

SOURCE REVISION
Which provider state/version of that object?

CHANGE CURSOR
Where is the connector in the change stream?

Examples include:

  • QuickBooks Id + SyncToken + CDC watermark;
  • Business Central record GUID + lastModifiedDateTime;
  • Fortnox entity ID + WebSocket offset;
  • SAP business object + extraction delta state.

A synchronization cursor must never be confused with the revision of a business object.

13. Source interface authority​

Transport alone does not establish source authority.

ACF v1 classifies source interfaces as:

released_standard
released_extraction
customer_extension
integration_adapter
legacy_supported
legacy_deprecated
manual

This allows ZAYAZ to distinguish, for example:

  • released SAP API;
  • released SAP extraction CDS;
  • Business Central custom AL API;
  • customer-managed BTP integration flow;
  • e-conomic legacy REST fallback; and
  • manual file fallback.

TrustGate and DaVE can use this classification when assessing provenance and drift.

14. Change capture​

ACF v1 defines change capture as a common abstraction.

CHANGE CAPTURE
     │
     ├── event
     │    ├── webhook
     │    ├── websocket
     │    └── business_event
     │
     ├── provider_delta
     │    ├── cdc
     │    ├── delta_extraction
     │    └── change_tracking
     │
     ├── watermark
     │    ├── modified_timestamp
     │    ├── date_range
     │    └── sequence
     │
     └── snapshot
          ├── full_reload
          └── file_snapshot

This covers the synchronization patterns discovered across the connector set.

15. Normative synchronization principle​

The ACF v1 synchronization principle is:

Change capture optimizes freshness. Reconciliation establishes completeness.

The common lifecycle is:

INITIAL SNAPSHOT
       ↓
SOURCE STATE
       │
   ┌───┼─────────────┐
   │   │             │
 EVENT DELTA      WATERMARK
   │   │             │
   └───┼─────────────┘
       ↓
AUTHORITATIVE READ
       ↓
SOURCE STATE
       ↓
RECONCILIATION

No event stream, webhook, WebSocket, CDC feed or watermark is assumed to eliminate reconciliation requirements.

16. Canonical mapping​

Provider-native fields are mapped through versioned ACF mappings.

A mapping identifies:

  • source interface;
  • source object;
  • source field/path;
  • canonical domain;
  • canonical field;
  • optional SSSR reference;
  • transformation mode; and
  • mapping version.

Source-native values remain preserved even where normalized values are created.

17. Semantic resolution​

A field mapping does not establish business or environmental meaning.

ACF therefore separates mapping from semantic resolution.

Example:

source quantity
      ↓
source unit
      ↓
item / material / activity
      ↓
transaction direction
      ↓
business semantic
      ↓
canonical activity
      ↓
method compatibility
      ↓
factor eligibility

A quantity is only an activity candidate until this chain is sufficiently resolved.

18. Physical activity rule​

The following is prohibited:

quantity present
      ↓
automatically treat as DQ3 activity

The required model is:

quantity
  +
unit
  +
source business meaning
  +
transaction direction
  +
activity semantic
  +
method-compatible unit
      ↓
validated activity

This rule applies across all ACF connectors.

19. Evidence relation​

Provider terminology is normalized into one evidence model.

Examples include:

QuickBooks       Attachable
Fortnox          file / voucher connection
e-conomic        attached document
Business Central attachment / PDF
SAP              business-document reference

ACF represents these as a canonical relation between:

source object
      ↓
evidence relation
      ↓
evidence object

The evidence relation states whether evidence:

  • supports;
  • documents;
  • verifies;
  • supersedes;
  • contradicts; or
  • provides context for

a source object.

20. ACF data-quality hierarchy​

The common quality model is normative.

ACF-DQ1 — Accounting-only estimate​

Typical basis:

  • monetary value;
  • account;
  • supplier;
  • accounting text.

ACF-DQ2 — Transaction / invoice / procurement evidence​

Typical basis:

  • invoice;
  • transaction line;
  • purchase order;
  • item/material identity;
  • source document.

ACF-DQ3 — Validated activity data​

Requires physical/activity information with sufficiently validated quantity, unit and semantics.

ACF-DQ4 — Supplier / product-specific primary data​

Primary information attributable to the actual supplier, product, service or activity.

ACF-DQ5 — Verified primary data​

Primary data with the required verification or assurance.

21. Quality upgrades preserve history​

If a DQ1 estimate is later replaced by DQ3 activity data, the earlier calculation remains part of TrustGate lineage.

The pattern is:

DQ1 result
    ↓
higher-quality evidence arrives
    ↓
new governed calculation
    ↓
DQ3 result

not:

DQ1 result overwritten

This preserves auditor-visible historical decision state.

22. Calculation execution and MICE​

When ACF supplies governed inputs to the Computation Hub, the calculation is executed by the relevant MICE micro-engine.

MICE identifies the micro-engine framework/family.

A material calculation result must identify the specific execution authority, including where applicable:

  • micro-engine identity / MEID;
  • method ID and method version;
  • input hash;
  • options hash;
  • dataset/factor identities;
  • output hash;
  • source lineage; and
  • TrustGate provenance.

Therefore a result should never record merely:

calculated_by: MICE

when the actual governed micro-engine and method are known.

23. Result scope​

A governed calculation may be attributed simultaneously to several scopes.

Example:

result_scope:
  organization: ECO-NOR-000123
  organizational_unit: EBU-NOR-000041
  project: EBP-NOR-000317

This allows the same underlying accounting activity to participate in:

  • organization-level GHG inventory;
  • business-unit reporting; and
  • project footprinting

without duplicating the physical event itself.

24. Allocation and consolidation​

Allocations must specify whether they are additive or merely attributed.

Example business-unit attribution:

attribution:
  role: attributed
  allocation:
    method: direct_source_assignment
    share: 1.0
  consolidation:
    included_in_parent: true
    additive_to_parent: false

Shared expenditure may use governed percentages or other approved allocation methods.

Allocation method and version must be preserved in calculation lineage.

25. TrustGate responsibilities​

TrustGate preserves the full chain:

source system
      ↓
source interface
      ↓
source identity
      ↓
source revision
      ↓
change/retrieval reason
      ↓
identity resolution
      ↓
canonical mapping
      ↓
semantic resolution
      ↓
data-quality assessment
      ↓
specific MICE micro-engine / method
      ↓
result scope
      ↓
reporting / verification

This allows ZAYAZ to explain not only the final result but how that result changed over time.

26. DaVE responsibilities​

DaVE monitors connector and source integrity, including:

  • authentication/authorization health;
  • capability drift;
  • source-interface changes;
  • API/schema drift;
  • event or delta gaps;
  • reconciliation gaps;
  • identity-resolution failures;
  • semantic-resolution failures;
  • source revision anomalies;
  • unit ambiguity;
  • source mapping failures; and
  • historical source mutation.

A technically reachable connector may still be semantically or evidentially degraded.

27. COSE responsibilities​

COSE compares available source evidence against the evidence required by the selected method or reporting requirement.

Example:

Required:
kWh electricity consumed

Available:
EUR electricity expenditure

Result:
DQ1 accounting estimate available
DQ3 activity evidence missing

ACF therefore supports progressive evidence improvement rather than false completeness.

28. FOGE responsibilities​

FOGE may use ACF-derived values only where:

  • the reporting field accepts the evidence type;
  • source scope is correct;
  • data quality satisfies the requirement;
  • required calculation has been executed; and
  • missing evidence has not been silently inferred.

29. ZARA responsibilities​

ZARA can use ACF metadata to explain:

  • where a value originated;
  • which connector/interface supplied it;
  • which source revision was processed;
  • which ECO/EBU/EBP scope applies;
  • how a source dimension was interpreted;
  • why a quantity did or did not qualify as activity data;
  • why a factor/method was selected;
  • which specific MICE micro-engine executed the calculation;
  • what quality level applies; and
  • what higher-quality evidence would improve the result.

30. Extension policy​

Common ACF objects use strict schemas.

Provider-specific differences belong inside namespaced extensions objects rather than becoming arbitrary top-level properties.

Example:

extensions:
  quickbooks:
    minor_version: 78
    realm_id: "..."

or:

extensions:
  sap:
    communication_scenario: SAP_COM_0303

This keeps the common model governed while allowing connector-specific fidelity.

31. Migration of existing connector specifications​

Existing connector specifications remain authoritative design sources.

They should be migrated to ACF v1 incrementally by:

  1. retaining their provider-specific technical detail;
  2. adding the common zayaz.acf.connector.v1 structure;
  3. moving provider-only properties into namespaced extensions where appropriate;
  4. expressing source interfaces through zayaz.acf.source-interface.v1;
  5. expressing capabilities through zayaz.acf.capability.v1;
  6. expressing synchronization through the common change-capture model; and
  7. generating customer-specific capability state only in zayaz.acf.connection-profile.v1.

Migration must not erase useful technical detail discovered during connector research.

32. Connector registry​

The governed registry currently includes the connector archetypes used to derive ACF v1:

ConnectorPrimary archetype
SIEFile accounting standard
XledgerDynamic-schema cloud ERP
TripletexAPI-native cloud accounting
Oracle NetSuiteDynamic enterprise cloud ERP
FortnoxAPI + event cloud accounting
Visma e-conomicOpenAPI / legacy hybrid cloud accounting
SAPEnterprise ERP ecosystem
Business CentralExtensible mid-market ERP
QuickBooks OnlineGlobal SMB cloud accounting

This set intentionally spans from simple accounting-file exchange through global enterprise ERP.

33. Normative ACF v1 principles​

The following are normative:

  1. Source-native values remain distinguishable from normalized, classified and derived values.
  2. Accounting expenditure is not automatically physical ESG activity.
  3. Source quantity is an activity candidate until unit and business semantics are validated.
  4. Change capture optimizes freshness; reconciliation establishes completeness.
  5. Customer effective capability is resolved, not inferred from generic provider documentation.
  6. Source identity and governed scope identity are separate.
  7. Source object revision and synchronization cursor are separate.
  8. ECO identifies organization scope; EBU identifies organizational-unit scope; EBP identifies project scope.
  9. EBU/EBP attribution must not automatically double count parent ECO inventories.
  10. Scope hierarchy is represented by versioned relationships rather than encoded in immutable IDs.
  11. Released or governed source interfaces are preferred over unstable internal implementation structures.
  12. Provider-specific differences belong in namespaced extensions.
  13. Data-quality upgrades preserve prior calculations and provenance.
  14. Evidence relationships use canonical semantics independent of provider terminology.
  15. A material calculation identifies the specific MICE micro-engine/method that executed it.
  16. No connector may silently manufacture regulatory completeness from insufficient source evidence.

34. Files​

The ACF v1 schema family is stored under:

schemas/acf/

Current artifacts:

zayaz.acf.connector.v1.schema.json
zayaz.acf.connection-profile.v1.schema.json
zayaz.acf.capability.v1.schema.json
zayaz.acf.source-interface.v1.schema.json
zayaz.acf.source-identity.v1.schema.json
zayaz.acf.scope-identity.v1.schema.json
zayaz.acf.identity-resolution.v1.schema.json
zayaz.acf.semantic-resolution.v1.schema.json
zayaz.acf.mapping.v1.schema.json
zayaz.acf.sync-state.v1.schema.json
zayaz.acf.evidence-relation.v1.schema.json
zayaz.acf.data-quality.v1.schema.json
acf.connector.registry.json

These constitute the initial governed ACF v1 connector contract.

GitHub RepoRequest for Change (RFC)
Last updated on by ZAYAZ