Organization: github.com/shapestone

Shape is a comprehensive parser infrastructure ecosystem for structured data formats. This repository contains documentation and code examples for the Shape ecosystem.

Shape provides a complete parser ecosystem built on reusable infrastructure:

• shape-core - Core parser infrastructure (AST, tokenizer, validator, grammar)
• Data Format Parsers - Production-ready parsers for JSON, YAML, XML, CSV, and more
• Tools & Utilities - Validation, transformation, and analysis tools

The Shape ecosystem is organized as independent repositories:

• shape - This repository: Documentation and code examples
• shape-core - Core parser infrastructure
• shape-json - JSON parser
• shape-yaml - YAML parser
• shape-xml - XML parser
• shape-csv - CSV parser
• shape-props - Properties parser

Each parser is a separate Git repository that can be used independently.

This repository (shape) contains:

• Documentation - Ecosystem overview, guides, and tutorials
• Examples - Cross-project code examples showing how parsers work together
• Getting Started - Onboarding materials for new users and contributors

This repository does NOT contain parser code - each parser lives in its own repository.

Each parser can be installed independently:

# Install JSON parser
go get github.com/shapestone/shape-json

# Install YAML parser
go get github.com/shapestone/shape-yaml

# Install XML parser
go get github.com/shapestone/shape-xml

To build your own parser:

# Install shape-core
go get github.com/shapestone/shape-core

See the Getting Started Guide for detailed instructions.

Production-ready parsers for standard data formats:

• shape-json - JSON parser with JSONPath query support
• shape-yaml - YAML parser and validator
• shape-xml - XML parser and validator
• shape-csv - CSV parser with schema validation
• shape-props - Java properties file parser

Command-line tools for validating data files:

• shape-jsonv - JSON validation CLI
• shape-yamlv - YAML validation CLI
• shape-xmlv - XML validation CLI
• shape-csvv - CSV validation CLI
• shape-textv - Text-based format validation CLI

shape-core provides the foundational components:

• AST Framework - Type-safe node definitions for validation schemas
• Tokenizer API - Build custom parsers with matchers
• Parser Interface - Standardized parsing patterns
• Schema Validator Framework - Semantic validation with custom types
• Grammar Verification - EBNF-based parser correctness verification

• Multiple Format Support - Parse JSON, YAML, XML, CSV, and Properties files
• Schema Validation - Validate data against schemas with rich error reporting
• Query Support - JSONPath and XPath query capabilities
• CLI Tools - Ready-to-use validation tools for CI/CD pipelines
• Production Ready - Battle-tested in production environments

• Reusable Infrastructure - Build new parsers on proven foundations
• Extensible - Add custom types and validation functions
• Well Documented - Comprehensive guides and examples
• LLM-Friendly - Grammars and guides optimized for AI-assisted development
• High Performance - Efficient parsing and validation

import "github.com/shapestone/shape-json"

// Parse JSON with schema validation
parser := shapejson.NewParser()
result, err := parser.Parse(jsonData)

import "github.com/shapestone/shape-core/pkg/tokenizer"

// Use Shape's tokenizer for your DSL
tok := tokenizer.NewTokenizer(
    tokenizer.StringMatcherFunc("LBrace", "{"),
    tokenizer.RegexMatcherFunc("Identifier", `[a-zA-Z_]\w*`),
)

# Validate JSON files
shape-jsonv validate data.json --schema schema.json

# Validate YAML files
shape-yamlv validate config.yaml

• Getting Started - Quick start guide
• Ecosystem Overview - Complete ecosystem documentation
• Contributing - Contribution guidelines

Each parser has its own documentation in its repository:

• shape-core docs
• shape-json docs
• shape-yaml docs
• shape-xml docs

If you're working on multiple parsers, you can organize them locally:

# Recommended local structure
mkdir shape-eco
cd shape-eco

# Clone repositories you're working on
git clone https://github.com/shapestone/shape.git
git clone https://github.com/shapestone/shape-core.git
git clone https://github.com/shapestone/shape-json.git
# ... clone others as needed

# Navigate to the parser repository
cd shape-json

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git commit -m "feat: add new feature"
git push origin feature/my-feature

# Navigate to shape-core
cd shape-core

# Development as usual
git checkout -b feature/my-feature
# ... make changes ...

• Go 1.25 or later
• Git

Shape is part of the broader Shapestone ecosystem:

• Inkling - Diagram parser using Shape's tokenizer

All Shape projects are licensed under the Apache License 2.0.

Copyright © 2020-2025 Shapestone

Shape is production-ready:

• ✅ 10+ parser projects built on shape-core
• ✅ Production-tested infrastructure
• ✅ Comprehensive test coverage
• ✅ Complete documentation
• ✅ Active development and maintenance

• Documentation: Start with this repository
• Issues: Report issues in the specific parser repository
• Discussions: https://github.com/shapestone/shape/discussions
• Security: See individual project SECURITY.md files

We welcome contributions! See CONTRIBUTING.md for guidelines.

For contributing to specific parsers or core infrastructure, see the CONTRIBUTING.md in the respective repository.