Module: ElasticGraph::JSONIngestion::SchemaDefinition::SchemaElements::HasJSONSchema

Included in:
FieldExtension, ScalarTypeExtension, TypeWithSubfieldsExtension
Defined in:
elasticgraph-json_ingestion/lib/elastic_graph/json_ingestion/schema_definition/schema_elements/has_json_schema.rb

Overview

Provides common JSON schema behavior for schema-definition fields and types.

Instance Method Summary collapse

Instance Method Details

#json_schema(**options) ⇒ void

Note:

We recommend using JSON schema validations in a limited fashion. Validations that are appropriate to apply when data is entering the system-of-record are often not appropriate on a secondary index like ElasticGraph. Events that violate a JSON schema validation will fail to index (typically they will be sent to the dead letter queue and page an oncall engineer). If an ElasticGraph instance is meant to contain all the data of some source system, you probably don’t want it applying stricter validations than the source system itself has. We recommend limiting your JSON schema validations to situations where violations would prevent ElasticGraph from operating correctly.

This method returns an undefined value.

Defines the JSON schema validations for this field or type. Validations defined here will be included in the generated json_schemas.yaml artifact, which is used by the ElasticGraph indexer to validate events before indexing their data in the datastore. In addition, the publisher may use json_schemas.yaml for code generation and to apply validation before publishing an event to ElasticGraph.

Can be called multiple times; each time, the options will be merged into the existing options.

This is required on a SchemaDefinition::SchemaElements::ScalarType (since we don’t know how a custom scalar type should be represented in JSON!). On a SchemaDefinition::SchemaElements::Field, this is optional, but can be used to make the JSON schema validation stricter than it would otherwise be. For example, you could use json_schema maxLength: 30 on a String field to limit the length.

You can use any of the JSON schema validation keywords here. In addition, nullable: false is supported to configure the generated JSON schema to disallow null values for the field. Note that if you define a field with a non-nullable GraphQL type (e.g. Int!), the JSON schema will automatically disallow nulls. However, as explained in the SchemaDefinition::SchemaElements::TypeWithSubfields#field documentation, we generally recommend against defining non-nullable GraphQL fields. json_schema nullable: false will disallow null values from being indexed, while still keeping the field nullable in the GraphQL schema. If you think you might want to make a field non-nullable in the GraphQL schema some day, it’s a good idea to use json_schema nullable: false now to ensure every indexed record has a non-null value for the field.

Examples:

Define the JSON schema validations of a custom scalar type

ElasticGraph.define_schema do |schema|
  schema.scalar_type "URL" do |t|
    t.mapping type: "keyword"

    # JSON schema has a built-in URI format validator:
    # https://json-schema.org/understanding-json-schema/reference/string.html#resource-identifiers
    t.json_schema type: "string", format: "uri"
  end
end

Define additional validations on a field

ElasticGraph.define_schema do |schema|
  schema.object_type "Card" do |t|
    t.field "id", "ID!"

    t.field "expYear", "Int" do |f|
      # Use JSON schema to ensure the publisher is sending us 4 digit years, not 2 digit years.
      f.json_schema minimum: 2000, maximum: 2099
    end

    t.field "expMonth", "Int" do |f|
      f.json_schema minimum: 1, maximum: 12
    end

    t.index "cards"
  end
end

Parameters:

  • options (Hash<Symbol, Object>) —

    JSON schema options



82
83
84
85
86
87
88
89
90
 
# File 'elasticgraph-json_ingestion/lib/elastic_graph/json_ingestion/schema_definition/schema_elements/has_json_schema.rb', line 82

def json_schema(**options)
  validatable_json_schema = Support::HashUtil.stringify_keys(options)

  if (error_msg = Support::JSONSchema.strict_meta_schema_validator.validate_with_error_message(validatable_json_schema))
    raise Errors::SchemaError, "Invalid JSON schema options set on #{self}:\n\n#{error_msg}"
  end

  json_schema_options.update(options)
end

#json_schema_options ⇒ Hash<Symbol, Object>

Returns JSON schema options.

Returns:

  • (Hash<Symbol, Object>) —

    JSON schema options



20
21
22
 
# File 'elasticgraph-json_ingestion/lib/elastic_graph/json_ingestion/schema_definition/schema_elements/has_json_schema.rb', line 20

def json_schema_options
  @json_schema_options ||= {}
end