Generador de JSON Schema

JSON Schema Generation: Inferring Structure from Sample Data

JSON Schema provides a declarative vocabulary for describing the structure, constraints, and validation rules of JSON documents. Writing schemas by hand is precise but laborious — especially for complex nested structures with dozens of properties, mixed-type arrays, and deeply embedded objects. This tool reverses the process: instead of authoring a schema first and then producing conforming data, you provide one or more sample JSON documents and the tool infers a complete JSON Schema that describes their structure. The generated schema captures property types, required fields, array item shapes, string format patterns, and nesting hierarchies — producing a standards-compliant schema ready for use in API validation, code generation, documentation, and contract testing workflows.

Schema inference is particularly valuable when working with undocumented APIs, legacy systems that produce JSON output without formal contracts, or rapid prototyping where the data shape stabilizes before anyone writes a formal specification. Rather than manually transcribing field names and types, you feed real data into the generator and receive a baseline schema that can be refined with additional constraints like minimum, maximum, pattern, or custom validation keywords.

Type Detection and Inference Strategies

The generator analyzes each value in your JSON sample and infers the most specific type permitted by the JSON Schema vocabulary. The inference engine applies the following strategies to produce accurate schemas rather than overly permissive catch-all definitions:

• Primitive types: String values map to "type": "string", numeric values to "type": "number" or "type": "integer" (when no decimal portion exists), booleans to "type": "boolean", and null to "type": "null". This direct mapping covers leaf values accurately.
• Object properties: Each key in a JSON object generates a corresponding entry in "properties" with its inferred type schema. All keys present in the sample are added to the "required" array by default, since the sample represents a complete instance.
• Array items: The generator inspects all elements of an array to determine whether they share a homogeneous type. Homogeneous arrays produce a single "items" schema. Heterogeneous arrays — containing elements of different types or structures — produce merged schemas that accommodate all observed variations.
• Nested objects: Objects within objects are recursively analyzed, generating nested schema definitions that mirror the full depth of your data structure. Each level receives its own "type": "object" with "properties" and "required" arrays.
• Null handling: When a property value is null, the generated schema uses a type array: "type": ["string", "null"] or similar, indicating that the property accepts null values. This preserves the semantic difference between nullable fields and absent fields.

The inference prioritizes accuracy over permissiveness. A single sample produces a schema that validates at least that sample; providing multiple samples allows the generator to compute intersections and unions, identifying which properties are truly required versus optional across instances.

String Format Detection and Enum Inference

Beyond basic type detection, the generator examines string values for patterns that match well-known formats defined in the JSON Schema specification. Detected formats are annotated using the "format" keyword, enabling validators to enforce structural constraints beyond simple type checking:

• date-time: Strings matching ISO 8601 date-time patterns (e.g., "2024-03-15T10:30:00Z") are annotated with "format": "date-time".
• date: Pure date strings like "2024-03-15" receive "format": "date".
• email: Values matching email address patterns are annotated with "format": "email".
• uri: Strings beginning with http:// or https:// and matching URI structure receive "format": "uri".
• uuid: Values matching the UUID pattern (8-4-4-4-12 hex digits) are annotated with "format": "uuid".
• ipv4 and ipv6: IP address strings are detected and annotated with their respective format keywords.

Additionally, when multiple samples are provided and a string property contains a small, repeating set of values (for example, "status" always being "active", "inactive", or "pending"), the generator can infer an "enum" constraint. This transforms a generic string property into a closed set of allowed values — significantly tightening the schema's validation power without manual intervention.

Format detection is conservative: only values that unambiguously match a recognized pattern receive format annotations. A string like "2024-13-45" would not be annotated as a date because the month and day values are invalid, even though the structural pattern resembles a date.

Required vs Optional Property Detection

Determining which properties are required versus optional is one of the most valuable aspects of schema inference. The strategy depends on whether you provide a single sample or multiple:

• Single sample: All properties present in the sample are marked as required. Since there is no counter-example showing the property absent, the safest assumption is that every observed property is mandatory. This produces a strict schema that can be relaxed later.
• Multiple samples: Properties appearing in every sample remain required. Properties missing from at least one sample are excluded from the "required" array, effectively making them optional. This statistical approach mirrors how a developer would manually determine optionality by examining multiple API responses.
• Array item inference: For arrays of objects, each element is treated as a separate sample. Keys appearing in every array item are required in the "items" schema; keys present in some but not all items are optional. This is particularly useful for heterogeneous collections where different item types share a common base.

The generated "required" array follows JSON Schema semantics exactly: only properties listed in "required" must be present for an instance to validate. Properties defined in "properties" but not in "required" are allowed but not mandatory — their schema applies only when the property is present.

JSON Schema Drafts and Output Conformance

The JSON Schema specification has evolved through several drafts, each adding vocabulary and refining semantics. The generator produces schemas conforming to Draft-07 by default, which offers the best balance of feature support and tooling compatibility:

• Draft-04: The oldest widely-deployed version. Uses id instead of $id and lacks if/then/else conditional keywords. Still used by older OpenAPI 3.0 tooling.
• Draft-06: Introduced const, contains, and propertyNames keywords. Uses $id for identification.
• Draft-07: Added if/then/else conditionals, readOnly/writeOnly, and string content encoding keywords. The most commonly supported draft across validators, IDE plugins, and code generators today.
• Draft 2019-09: Introduced $vocabulary, unevaluatedProperties, and recursive references. More expressive but less universally supported by tooling.
• Draft 2020-12: The current latest specification. Refined dynamic references and introduced prefixItems for tuple validation (replacing the array form of items).

The generated schema includes the appropriate $schema meta-schema URI, allowing validators to apply the correct dialect semantics. For maximum compatibility with existing toolchains — including OpenAPI 3.1, Ajv, and JSON Schema Form — Draft-07 remains the recommended output target unless your specific tooling requires a newer draft.

Practical Applications: From Inference to Validation Pipelines

Schema generation bridges the gap between untyped JSON data and formal validation contracts. Common workflows built around inferred schemas include:

• API contract bootstrapping: Record a handful of real API responses, generate a schema, and use it as the starting point for an OpenAPI specification. This bottom-up approach produces schemas grounded in actual behavior rather than aspirational documentation.
• Test data validation: Generate a schema from production data samples, then validate test fixtures against it to ensure mock data accurately represents real-world structure. Catches drift between test assumptions and production reality.
• Configuration file validation: Application configs often lack formal schemas. Generate one from existing valid configs, then integrate schema validation into CI/CD to prevent malformed configurations from reaching production.
• Data pipeline contracts: ETL pipelines consuming JSON from external sources benefit from generated schemas as input validation gates. An inferred schema rejects malformed records before they contaminate downstream transformations.
• Documentation generation: JSON Schema serves as input for documentation generators that produce human-readable API docs, interactive form builders, and data dictionaries. An inferred schema provides the structural backbone for these tools.

In each case, the generated schema is a starting point — not a final product. Developers typically refine inferred schemas by adding description annotations, tightening numeric ranges, adding pattern constraints for string formats, or introducing additionalProperties: false to create closed schemas that reject unknown fields.

Code Examples

Sample JSON input and generated JSON Schema output

// Input: Sample JSON data
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme API",
  "version": "2.1.0",
  "active": true,
  "endpoints": [
    {
      "path": "/users",
      "method": "GET",
      "rate_limit": 1000
    },
    {
      "path": "/users/{id}",
      "method": "GET",
      "rate_limit": 500
    }
  ],
  "created_at": "2024-03-15T10:30:00Z",
  "homepage": "https://api.acme.com",
  "deprecated": null
}

Output:

// Generated JSON Schema (Draft-07)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "method": { "type": "string" },
          "rate_limit": { "type": "integer" }
        },
        "required": ["path", "method", "rate_limit"]
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "homepage": {
      "type": "string",
      "format": "uri"
    },
    "deprecated": {
      "type": ["string", "null"]
    }
  },
  "required": [
    "id", "name", "version", "active",
    "endpoints", "created_at", "homepage", "deprecated"
  ]
}

Standards & Specifications

• JSON Schema Specification (Draft-07) — The primary draft used for generated output — defines validation keywords, type system, and format vocabulary
• JSON Schema Draft 2020-12 — The latest JSON Schema specification — introduces prefixItems, dynamic references, and vocabulary system
• JSON Schema Validation (Draft-07) — Defines validation keywords (format, minimum, maximum, pattern, enum) used in generated schemas
• RFC 8259 (JSON) — The JSON data interchange format specification — defines the input format this tool analyzes