---
title: Blueprints & Semantic Markdown
category: Organization
icon: 🧩
sort_order: 18
slug: semantic-blueprints
canonical_url: https://basaltnotes.com/guides/semantic-blueprints
markdown_url: https://basaltnotes.com/guides/semantic-blueprints.md
---
# Blueprints & Semantic Markdown

Blueprints add bounded types and validation to ordinary Markdown notes. The Markdown file remains canonical; Basalt does not replace it with an opaque object record.

## Portable namespace

Applying a Blueprint writes readable YAML like this:

```yaml
---
status: active
owner: Alex
basalt:
  type: project
  blueprint: custom.project
  blueprint_version: 2
  entity_id: entity:01JPROJECT
  links:
    - type: decision
      id: decision:launch-scope
      label: Launch scope
  external:
    - provider: github
      object_type: issue
      id: aketchel/BasaltNotes#72
      label: Blueprint epic
  behaviors:
    templateId: project-review
    quarryViewId: active-projects
    recipeId: weekly-review
    skillId: product-operations
    forgeAction: project-review
---
```

Another Markdown editor sees normal YAML and normal body text. Basalt understands the namespaced values, while unknown properties remain untouched.

## Custom types and typed validation

The note inspector can create a custom Blueprint with required or recommended properties. Supported bounded property types are text, number, boolean, date, date-time, enum, tags, text list, internal link, and external reference. Validation reports errors and warnings without coercing or deleting raw values.

Allowed tag roots provide a schema-aware vocabulary while still permitting nested tags such as `project/client-a`. Tags outside the declared vocabulary produce a warning, not destructive cleanup.

## Versions and migrations

Every custom save creates an immutable Blueprint version snapshot. A new version may declare explicit field renames and defaults. Notes remain on their recorded version until a user previews and applies the migration. The preview updates only YAML fields named by the migration and preserves the Markdown body and unrelated frontmatter.

## Entity links

Internal links store a Basalt entity type and stable ID. Basalt resolves indexed notes and tasks plus Agent, Living Skill, Prompt Recipe, Quarry, meeting, decision, Forge, and compiled-concept IDs. The derived local entity index tracks a note's stable ID, so a normal rename or move updates the target path without rewriting every source link.

External references store a provider, object type, and stable external object ID. A display URL is optional and never substitutes for stable identity. Connections still enforce their own account scopes and permissions.

Blueprint behavior bindings identify existing templates, Quarries, Recipes, Skills, or Forge actions. They do not bypass each subsystem's entitlement, enablement, policy, preview, approval, or audit boundary. This is a versioned semantic foundation, not a claim that every future property type or external-system schema is already built.