ObjectSchema extension type

A JSON Schema definition for an object with properties.

ObjectSchema is used to define the expected structure, data types, and constraints for MCP argument objects. It allows you to specify:

See https://json-schema.org/understanding-json-schema/reference/object.html for more details on object schemas.

Example:

To define a schema for a product object that requires productId and productName, has an optional price (non-negative number) and optional tags (list of unique strings), and optional dimensions (an object with required numeric length, width, and height):

final productSchema = ObjectSchema(
  title: 'Product',
  description: 'Schema for a product object',
  required: ['productId', 'productName'],
  properties: {
    'productId': Schema.string(
      description: 'Unique identifier for the product',
    ),
    'productName': Schema.string(description: 'Name of the product'),
    'price': Schema.num(
      description: 'Price of the product',
      minimum: 0,
    ),
    'tags': Schema.list(
      description: 'Optional list of tags for the product',
      items: Schema.string(),
      uniqueItems: true,
    ),
    'dimensions': ObjectSchema(
      description: 'Optional product dimensions',
      properties: {
        'length': Schema.num(),
        'width': Schema.num(),
        'height': Schema.num(),
      },
      required: ['length', 'width', 'height'],
    ),
  },
  additionalProperties: false, // No other properties allowed beyond those defined
);

This schema can then be used with the validate method to check if a given JSON-like map conforms to the defined structure.

For example, valid data might look like:

{
  "productId": "ABC12345",
  "productName": "Super Widget",
  "price": 19.99,
  "tags": ["electronics", "gadget"],
  "dimensions": {"length": 10, "width": 5, "height": 2.5}
}

And invalid data (e.g., missing productName, or an extra undefined property):

{
  "productId": "XYZ67890",
  "price": 9.99
}

{
  "productId": "DEF4567",
  "productName": "Another Gadget",
  "color": "blue" // Invalid if additionalProperties is false
}
on
Implemented types
Available extensions

Constructors

ObjectSchema.new({String? title, String? description, Map<String, Schema>? properties, Map<String, Schema>? patternProperties, List<String>? required, Object? additionalProperties, bool? unevaluatedProperties, StringSchema? propertyNames, int? minProperties, int? maxProperties})
factory
ObjectSchema.fromMap(Map<String, Object?> _value)

Properties

additionalProperties → Object?
Rules for additional properties that don't match the properties or patternProperties schemas.
no setter
allOf → List<Schema>?
Schema combinator that requires all sub-schemas to match.
no setterinherited
anyOf → List<Schema>?
Schema combinator that requires at least one of the sub-schemas to match.
no setterinherited
description → String?
A description of this schema.
no setterinherited
maxProperties → int?
The maximum number of properties in this object.
no setter
minProperties → int?
The minimum number of properties in this object.
no setter
not → List<Schema>?
Schema combinator that requires none of the sub-schemas to match.
no setterinherited
oneOf → List<Schema>?
Schema combinator that requires exactly one of the sub-schemas to match.
no setterinherited
patternProperties → Map<String, Schema>?
A map of the property patterns of the object to the nested Schemas for those properties.
no setter
properties → Map<String, Schema>?
A map of the properties of the object to the nested Schemas for those properties.
no setter
propertyNames → StringSchema?
A list of valid patterns for all property names.
no setter
required → List<String>?
A list of the required properties by name.
no setter
title → String?
A title for this schema, should be short.
no setterinherited
type → JsonType?
The JsonType of this schema, if present.
no setterinherited
unevaluatedProperties → bool?
Similar to additionalProperties but more flexible, see https://json-schema.org/understanding-json-schema/reference/object#unevaluatedproperties for more details.
no setter

Methods

validate(Object? data) → List<ValidationError>

Available on Schema, provided by the SchemaValidation extension

Validates the given data against this schema.