Contracts

Reusable member fragments

A Block may declare contracts at root level to compose one or more contract Blocks — reusable partial definitions whose member fragments merge into the Block's effective definition alongside its baseType chain.

Contracts versus baseType

baseType establishes framework taxonomy and branch membership through single inheritance, while contracts mix in member fragments across Blocks that share no common baseType ancestor. Contracts are declared only on the document root, never on nested Sub-Blocks.

The effective definition merges the baseType chain first, then contracts in declaration order, then local Block declarations — later contracts override earlier ones, and the Block itself overrides every contract.

Completing a partial contract member

A contract may declare an incomplete member — for example an identifier property without a type — and the concrete Block completes it with override="true", the same rule used to refine an inherited baseType member.

Mixing in a contract

A Block can declare both a baseType and a contracts list, mixing in a member fragment that its baseType chain does not otherwise provide.

<!-- A contract: an abstract Block with one partial, untyped member -->
<acme:Identifiable xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core">

  <baseType>
    core:Block
  </baseType>
  <abstract>
    true
  </abstract>
  <properties>
    <sku />
  </properties>
</acme:Identifiable>

<!-- Basket mixes in the contract and completes "sku" with a concrete type -->
<acme:Basket xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core"
  xmlns:type="org.blockml.bml.type">

  <baseType>
    core:Block
  </baseType>
  <contracts>
    <acme:Identifiable />
  </contracts>
  <properties>
    <sku override="true" type="type:Text" />
  </properties>
</acme:Basket>

Basket's contracts list names Identifiable as a direct Block reference, and its properties complete sku with override="true" and a concrete type, exactly as PartialMemberOverrides requires. That entry contributes its member fragment to Basket's effective definition after the baseType chain — Basket gains the sku fragment without needing a common ancestor with Identifiable.

What to carry into the next pages

After this page, readers should be able to choose baseType or a contract when they need to reuse a member fragment, before moving on to how Blocks are named and located.

Continue with namespaces and FQNs