Core Use Cases

Three problems, one principle

BlockML is designed around three core use cases that all rest on the same principle: information is represented as a structured, semantic model instead of unstructured text or implementation-specific data.

Structured documentation and domain modeling

As a structured alternative to Markdown, a BlockML document can serve simultaneously as documentation for humans, context for AI systems, and structured input for tools — because the BlockML model, not the generated documentation, is the source of truth. BlockML makes documentation structure explicit while still preserving human-readable Markdown content inside documentation blocks.

BlockML can also describe arbitrary domains as vocabularies of Blocks, types, properties, relationships, capabilities, and compositions; renderers then interpret that same model differently for each target. BlockML describes what something is; renderers decide how that description manifests in a particular environment.

AI workspaces

Instead of repeatedly asking an AI to produce new documents, BlockML lets the AI work directly on a structured model that it can inspect, validate, extend, and transform — making intermediate states explicit, not just the final result. The model is the workspace; the AI works on the model; renderers manifest its current state.

Recognizing when BlockML fits

A documentation Block is ordinary BlockML — the same Block grammar used for domain models and AI workspaces, applied to the structured-documentation use case.

<!-- A documentation Block: identity plus the Documentation base type -->
<doc:CoreUseCases xmlns="http://blockml.org/bml"
  xmlns:core="org.blockml.bml.core"
  xmlns:doc="org.blockml.bml.documentation">

  <baseType>
    core:Documentation
  </baseType>
</doc:CoreUseCases>

The element tag doc:CoreUseCases identifies this Block exactly like acme:Widget did on the previous page; only the baseType differs, pointing to core:Documentation instead of core:Block directly. The same root-Block shape shown here also identifies domain models and AI workspace state — recognizing that shape is how a reader recognizes any of the three use cases in practice.

What to carry into the next pages

After this page, readers should be able to recognize a problem — structured documentation, domain modeling, or an AI workspace — that fits one of BlockML's three core use cases.

Continue with the ontological principle