Sagebrush Standards Specification

Computable Document Workflows

The Sagebrush Standards Specification (now part of Neon Notations) documents a system for computable document workflows that combines legal document templates, interactive forms, and automated processes into unified files called Notations.

Note: Sagebrush Standards are now integrated into the broader Neon Notations framework. This specification remains the technical foundation for how Notations are structured and validated.

Overview

The Sagebrush Standards Specification provides a comprehensive system for creating legal documents that are both human-readable and machine-processable. By integrating documents, questionnaires, and workflows into single-file notations, we enable AI systems to better understand and process legal content.

Key Components

Three Core Parts

The system integrates:

1. Documents - Dynamic templates with variable interpolation
2. Questionnaires - Data collection forms with validation
3. Workflows - Automated triggered actions based on state machines

These three components are combined into single-file notations that encapsulate the entire legal process.

File Structure

Notations use a dual-structure format:

1. YAML Frontmatter (delimited by triple dashes ---)

   • Contains metadata
   • Defines state machines for workflows
   • Specifies questionnaire logic

2. Markdown Content

   • Legal document template
   • Uses Liquid templating syntax for dynamic variables
   • Supports rich formatting and structure

Required YAML Fields

Every Notation must include the following fields in its frontmatter:

Core Metadata

• code: Unique identifier across all notations

  • Must be globally unique
  • Used for referencing and indexing

• title: Human-readable title

  • Maximum 255 characters
  • Describes the notation’s purpose

• description: Purpose statement

  • Explains what the notation does
  • Helps users understand when to use it

Respondent Configuration

• respondent_type: Specifies who can respond
  • Options: "org" or "org_and_person"
  • Determines available questionnaire fields

State Machine Definitions

• flow: Client questionnaire state machine

  • Defines the user-facing workflow
  • Guides data collection process

• alignment: Staff review state machine

  • Defines the internal review workflow
  • Manages approval and validation steps

State Machine Requirements

Both the flow and alignment state machines must adhere to strict requirements:

Structure Requirements

1. BEGIN state: Every state machine must start with a BEGIN state
2. END state: At least one path must reach an END state
3. Valid paths: All states must be reachable from BEGIN
4. No infinite loops: Prevent endless cycles in the workflow

Question References

• All questions must reference existing database questions
• Question IDs must be valid and accessible
• Question types must match expected data formats

Example State Machine

flow:
  BEGIN:
    - question: "org_name"
      next: "COLLECT_DETAILS"
  COLLECT_DETAILS:
    - question: "org_address"
      next: "REVIEW"
  REVIEW:
    - question: "confirm_data"
      next: "END"
  END: {}

Document Generation Methods

The system supports two distinct methods for generating final documents:

1. PDF Form Population

Uses field mappings to populate existing PDF forms:

• Maps notation variables to PDF form fields
• Preserves original PDF formatting
• Suitable for standardized government forms
• Requires pre-existing PDF templates

2. Markdown Generation

Uses Liquid templating for dynamic content generation:

• Generates documents from scratch
• Full control over formatting and structure
• Supports complex conditional logic
• Outputs to PDF, HTML, or other formats

Variable Interpolation

Documents use Liquid syntax for variable interpolation:

Basic Variables

{{variable_name}}

Variables with Filters

Liquid supports filters for formatting:

{{date_field | date: "%B %d, %Y"}}
{{amount | currency}}
{{text_field | upcase}}

Common Filters

• Date formatting: date: "%Y-%m-%d"
• Currency formatting: currency
• Text transformation: upcase, downcase, capitalize
• String manipulation: truncate, strip, replace

Conditional Logic

{% if variable_name %}
  Content when variable exists
{% else %}
  Content when variable doesn't exist
{% endif %}

Validation Rules

The specification enforces multiple validation rules to ensure notation quality:

YAML Syntax

• Must be valid YAML
• Proper indentation and structure
• Correct data types for all fields

Unique Identifiers

• Code values must be unique across all notations
• No duplicate codes allowed in the system

State Reachability

• All states must be reachable from BEGIN
• At least one path must reach END
• No orphaned states

Variable Correspondence

• All variables in templates must have data sources
• Variables must correspond to:
  • Questionnaire responses
  • Database fields
  • System-provided values

Data Integrity

• Question references must be valid
• Data types must match expected formats
• Required fields must be present

Implementation Guidelines

Creating a New Notation

1. Define the code: Choose a unique identifier
2. Write the frontmatter: Include all required fields
3. Design the state machines: Map out flow and alignment
4. Create the template: Write the document with Liquid variables
5. Validate: Ensure all validation rules pass

Testing Notations

• Test all workflow paths
• Verify variable interpolation
• Check PDF generation (if applicable)
• Validate state machine logic
• Ensure question references work

Version Control

• Track all notation changes
• Document breaking changes
• Maintain backward compatibility when possible
• Use semantic versioning

Integration with Neon Notations

Sagebrush Standards now serve as the technical foundation for Neon Notations:

• All Sagebrush Standards specifications are valid Neon Notations
• Neon Notations extends Sagebrush with additional features
• The core structure and validation remain the same
• New features are backward-compatible

Benefits

For Legal Professionals

• Reduced repetition: Write templates once, use many times
• Consistency: Standardized formats across documents
• Efficiency: Automated workflows save time
• Quality: Built-in validation reduces errors

For AI Systems

• Structured data: Clear semantic meaning
• Predictable format: Consistent patterns across notations
• Validation: Automated checks ensure quality
• Grounding: Reliable foundation for AI reasoning

For Organizations

• Scalability: Handle high volumes efficiently
• Compliance: Built-in validation ensures standards
• Auditability: Version control tracks all changes
• Integration: Works with existing systems

Best Practices

Template Design

• Use clear, descriptive variable names
• Include helpful comments in YAML
• Structure documents logically
• Test with real data

State Machine Design

• Keep workflows simple and linear when possible
• Provide clear user guidance at each step
• Handle error cases gracefully
• Document complex logic

Variable Management

• Document all available variables
• Use consistent naming conventions
• Provide sensible defaults
• Validate data types

Support and Resources

Contact

For questions or support regarding the Sagebrush Standards specification:

Email: [email protected]

Documentation

• Neon Notations Overview
• GitHub Repository
• Technical specification (this page)

Community

• Join our open source community
• Contribute improvements and templates
• Share your use cases
• Help refine the standards

Future Development

Ongoing work includes:

• Enhanced validation tools
• Additional template examples
• Expanded filter library
• Improved error messaging
• Better testing frameworks

Sagebrush Standards are now part of Neon Notations, the Neon Law Foundation’s comprehensive framework for legal documentation and computable contracts. All standards are open source and freely available.

Learn more about Neon Notations | View on GitHub