Connect SDK

Application manifest

Declare application identity, callback routes, collection compatibility, provisioning, and notification criteria in one bundled v1 file.

Bundle the manifest with the application, load it through the SDK, and validate it as part of the build. Connect identifies its canonical JSON by digest.

Canonical schema:mdbase-app.v1.json

Shared identity fields

Field	Rule
`manifest_version`	`1` throughout the current Connect pre-release
`distribution`	`web` when omitted, or explicit `portable`
`id`	Stable lowercase reverse-domain identifier with at least three labels
`name`	Human-readable name shown during authorization

Web and native-shell manifests

Existing v1 manifests may omit distribution; that means web. They declare an HTTPS homepage and at least one redirect_uris entry on the same origin. An optional icon stays on the homepage origin.

Downloaded HTML manifests

A downloaded file declares distribution: "portable" and omits homepage and redirect_uris. Its optional project_url is HTTPS presentation metadata, not publisher verification. An optional icon must share that project URL's origin.

Portable manifest example

{
  "manifest_version": 1,
  "distribution": "portable",
  "id": "dev.example.portable-worklog",
  "name": "Portable worklog",
  "project_url": "https://worklog.example/source",
  "requirements": {
    "access": "full_collection",
    "contracts": []
  }
}

Portable manifests use key-bound short-code authorization, can accept local or hosted collections, and keep their credentials in memory when opened from file://. See the portable HTML application guide.

Collection requirements

Requirements identify compatible collections. The user grants access in a separate authorization step.

Field	Meaning
`contracts`	Exact contract IDs and semantic versions the app understands
`access: "contract"`	Default. Limit record access to types that provide required contracts
`access: "full_collection"`	Request collection-wide features such as saved views or type administration
`collection_kind: "hosted"`	Offer only provider-backed collections, including to portable files

Leave collection_kind out when either authority is acceptable.

The SDK selects direct, relay, or hosted transport automatically after approval.

Provision a missing contract safely

A manifest may carry a complete transactional type pack. During approval, the authority validates every declared digest, preflights the contract, types, and referenced schemas together, and writes all resources or none. It then reopens the collection and pins the exact contract and implementation digests before creating the grant. General type administration requires a separate create_type grant.

Work-item contract example

{
  "manifest_version": 1,
  "id": "dev.example.worklog",
  "name": "Worklog",
  "homepage": "https://worklog.example",
  "redirect_uris": [
    "https://worklog.example/auth/mdbase/callback"
  ],
  "requirements": {
    "contracts": [
      { "id": "example.work-item", "version": "1.0.0" }
    ]
  },
  "provisions": {
    "type_packs": [
      {
        "provides": [
          { "id": "example.work-item", "version": "1.0.0" }
        ],
        "manifest": {
          "kind": "mdbase.type-pack",
          "id": "example.work-items",
          "version": "1.0.0",
          "name": "Work items",
          "resources": [
            {
              "kind": "contract",
              "source": "contracts/example.work-item.md",
              "target": "_contracts/example.work-item.md",
              "digest": "sha256:9cd7f8e4b23ba20aaeaec3f7e209c6ba8de3fa5cd224204f2baef4e14dd69936"
            },
            {
              "kind": "type",
              "source": "types/work-item.md",
              "target": "_types/work-item.md",
              "digest": "sha256:2be7d8a5cd316fe2e4d31fa49b1d09f2d26a584846392b3ef21ff0219893230b"
            }
          ]
        },
        "resources": [
          {
            "source": "contracts/example.work-item.md",
            "document": "---\nkind: mdbase.contract\ncontract_type: record\nid: example.work-item\nversion: 1.0.0\nrecord_schema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: https://json-schema.org/draft/2020-12/schema\n    type: object\n    additionalProperties: false\n    properties:\n      title: { type: string }\n    required: [title]\n---\n"
          },
          {
            "source": "types/work-item.md",
            "document": "---\nkind: mdbase.type\nname: work-item\nversion: 1\nschema:\n  dialect: json-schema-2020-12\n  value:\n    type: object\n    additionalProperties: true\n    properties:\n      title: { type: string }\n    required: [title]\nimplements:\n  - contract: example.work-item\n    version: 1.0.0\n    fields:\n      title: title\n---\n"
          }
        ]
      }
    ]
  }
}

A pack may only claim contracts listed in requirements.contracts. A target with different bytes is a conflict, not an implicit overwrite. Repeating the same pack is idempotent.

Native application callbacks

Native shells open authorization in the system browser and may list a private-use scheme that exactly matches, or extends, the application ID.

Native callback example

{
  "manifest_version": 1,
  "id": "dev.example.workouts",
  "name": "Example Workouts",
  "homepage": "https://workouts.example",
  "redirect_uris": [
    "https://workouts.example/auth/mdbase/callback",
    "dev.example.workouts://auth/mdbase/callback"
  ],
  "requirements": { "contracts": [] }
}

Pass a navigate adapter to MdbaseConnect, then call completeAuthorization(callbackUrl) when the deep link returns to the application.

Changing the manifest

Any canonical manifest change creates a new application identity digest. It cannot silently broaden an existing grant. The existing installation stays bound to its approved declaration until the user completes authorization for the changed one.

This is especially important for new contracts, notification criteria, and changed callback routes. Handle notification_reauthorization_required by starting authorization again.