GenSON Documentation

GenSON does not infer enum keywords automatically. To use enums, you must activate them by seeding a node with a schema containing the enum keyword (an empty list [] is sufficient to activate it).

Behavioral notes:

• Once activated, the node captures all encountered values into a deduplicated list instead of inferring a type.
• Supported values: Only scalar values (string, number, boolean, and null) are supported. Passing lists or objects to an enum node will raise a TypeError.
• Ordering: Values are merged as a set; the order in the output list is not guaranteed.
• Const: To simulate a const keyword, seed with enum, and if only one value is captured, manually replace the enum block with {"const": value}.

>>> from genson import SchemaBuilder
>>> builder = SchemaBuilder()
>>> # Activate enum for the 'status' property
>>> builder.add_schema({'type': 'object', 'properties': {
...     'status': {'enum': []}
... }})
>>> builder.add_object({'status': 'active'})
>>> builder.add_object({'status': 'inactive'})
>>> builder.add_object({'status': 'active'})
>>> builder.to_schema()
{'$schema': 'http://json-schema.org/schema#', 
 'type': 'object', 
 'properties': {'status': {'enum': ['inactive', 'active']}}, 
 'required': ['status']}

By default, GenSON interprets arrays using List validation (one schema for all items). To force Tuple validation (a different schema for every array position), seed the SchemaBuilder with a schema containing an items array.

Note: You can provide an 'imperfect' seed schema (e.g., an empty items list); GenSON will automatically adjust it to be a valid JSON Schema.

>>> from genson import SchemaBuilder
>>> builder = SchemaBuilder()
>>> # Default behavior: List validation
>>> builder.add_object(['one', 1])
>>> builder.to_schema()
{'$schema': 'http://json-schema.org/schema#', 'type': 'array', 'items': {'type': ['integer', 'string']}}

>>> # Forced behavior: Tuple validation via seeding
>>> builder = SchemaBuilder()
>>> seed_schema = {'type': 'array', 'items': []}
>>> builder.add_schema(seed_schema)
>>> builder.add_object(['one', 1])
>>> builder.to_schema()
{'$schema': 'http://json-schema.org/schema#', 'type': 'array', 'items': [{'type': 'string'}, {'type': 'integer'}]}

GenSON defaults to using properties. To use patternProperties (validating keys against RegEx strings), you must seed the builder with an object schema containing a patternProperties dictionary.

Important details:

• Uses Python-flavor RegEx.
• If a property matches both a specific properties entry and a patternProperties regex, GenSON prefers and updates the properties entry.
• If a key matches multiple patterns, the specific pattern updated is not guaranteed.
• You can use None as a placeholder value for the pattern keys in your seed schema.

>>> from genson import SchemaBuilder
>>> builder = SchemaBuilder()
>>> # Seed with patternProperties using None as a placeholder
>>> builder.add_schema({'type': 'object', 'patternProperties': {r'^\d+$': None}})
>>> builder.add_object({'1': 1, '2': 2, '3': 3})
>>> builder.to_schema()
{'$schema': 'http://json-schema.org/schema#', 'type': 'object', 'patternProperties':  {'^\\d+$': {'type': 'integer'}}}

To add custom logic (such as tracking specific JSON schema keywords like minimum or maximum), you must follow a three-step process:

1. Create a custom SchemaStrategy class: Inherit from an existing strategy (like SchemaStrategy or TypedSchemaStrategy) and override methods to handle new keywords or data types.
2. Create a SchemaBuilder subclass: Incorporate your custom strategy into a new builder class.
3. Use your custom SchemaBuilder: Use this subclass instead of the standard SchemaBuilder to perform schema generation.

GenSON uses the Strategy Pattern to map nodes in an object or schema to specific strategy instances. Each instance maintains the state for that specific node.

from genson import SchemaBuilder
from genson.schema.strategies import Number

class MinNumber(Number):
    # 1. Custom Strategy
    KEYWORDS = (*Number.KEYWORDS, 'minimum')
    # ... implementation ...

class MinNumberSchemaBuilder(SchemaBuilder):
    # 2. Custom Builder
    EXTRA_STRATEGIES = (MinNumber,)

# 3. Usage
builder = MinNumberSchemaBuilder()
builder.add_object(5)
print(builder.to_schema())

If you need to manually verify a release (e.g., for a TestPyPI rc or a final PyPI release) outside of the automated GitHub Action jobs, use the following script. This creates a temporary virtual environment, installs the specific version from the target index, and runs basic checks.

# Extract version from tag (assumes tag format v1.4.0)
VERSION="$(git describe --tags --exact-match | sed 's/^v//')"
VENV_DIR="$(mktemp -d)"

# Setup venv
python3 -m venv "$VENV_DIR/venv"

# Install from TestPyPI (use --index-url for TestPyPI, or omit for PyPI)
"$VENV_DIR/venv/bin/pip" install \
  --index-url https://test.pypi.org/simple/ "genson==$VERSION"

# Verify import and version
"$VENV_DIR/venv/bin/python" -c "import genson; print(genson.__version__)"

# Verify CLI
"$VENV_DIR/venv/bin/python" -m genson --version

# Verify CLI functionality
echo '{"hi": 5}' | "$VENV_DIR/venv/bin/genson"

# Cleanup
rm -rf "$VENV_DIR"