@fnet/object-from-schema

This project provides a utility for generating structured YAML documents from JSON schemas. It is designed to enhance data input processes by leveraging schemas to prompt users for input, allowing for the creation or updating of YAML files that are well-structured and documented with comments. Users can also provide reference objects to pre-fill values, making the data entry process more efficient.

How It Works

The utility takes a JSON schema and optionally a reference object, which contains default values. Based on the schema, it prompts users to input data for each schema property in an interactive manner, using various input types like text, numbers, selects, and others. It accommodates optional and required fields and provides default values where applicable. Once the data is captured, it converts it into a YAML document, completing the process by ensuring the YAML file is enriched with comments derived from the schema's descriptions.

Key Features

• Interactive Prompts: Uses intuitive prompts based on schema definitions to guide users through data entry.
• Flexible Input Handling: Handles different data types and supports schema features like oneOf and nested objects.
• Reference and Defaults: Allows using pre-existing objects to supply default values, making data entry faster.
• Multi-Format Support: Outputs generated data in JSON, YAML, or both formats depending on user preference.
• Schema-Based Comments: Automatically includes comments in YAML from schema descriptions for better documentation.

Conclusion

This utility simplifies the process of generating and managing YAML documents using JSON schemas. It ensures that the data collected is consistent with the schema specifications and makes the input process both flexible and user-friendly. Whether updating existing data or creating new YAML documents, this tool offers a straightforward approach that includes built-in documentation support.

@fnet/object-from-schema Developer Guide

Overview

The @fnet/object-from-schema library is designed for developers who need to generate YAML or JSON formatted objects from a given JSON schema. This library simplifies the process by leveraging user prompts for input values and supports complex schema features such as oneOf, anyOf, and allOf, along with the ability to use default values from reference objects.

Installation

To install the library, use either npm or yarn:

npm install @fnet/object-from-schema

or

yarn add @fnet/object-from-schema

Usage

Below is a step-by-step guide on using @fnet/object-from-schema to generate a YAML or JSON object based on a provided JSON schema.

Basic Example

To generate an object from a schema, you can call the main function exported by the library. Here’s a simple use case:

import objectFromSchema from '@fnet/object-from-schema';

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', description: 'Name of the person' },
    age: { type: 'number', description: 'Age of the person' },
  },
  required: ['name']
};

const ref = {
  name: 'John Doe'
};

(async () => {
  const result = await objectFromSchema({ schema, ref, format: 'yaml' });
  console.log(result); // Outputs a YAML string with comments
})();

Using a Reference Object

The function can accept a reference object that provides default values for the schema properties, allowing easy overriding and default value usages:

const ref = {
  name: 'Alice'
};

const result = await objectFromSchema({ schema, ref, format: 'json' });
console.log(result); // Outputs a JSON string with default values applied

Output Formats

The library supports different output formats through the format option:

• json: Returns the result in JSON format.
• yaml: Returns the result in YAML format.
• all: Returns both formats.

const result = await objectFromSchema({ schema, format: 'all' });
console.log(result.json); // JSON format output
console.log(result.yaml); // YAML format output

Examples

Example with oneOf

const schemaWithOneOf = {
  type: 'object',
  oneOf: [
    {
      properties: {
        type: { const: 'student' },
        grade: { type: 'number', description: 'Grade of the student' }
      },
    },
    {
      properties: {
        type: { const: 'teacher' },
        subject: { type: 'string', description: 'Subject taught by the teacher' }
      },
    },
  ],
};

const result = await objectFromSchema({ schema: schemaWithOneOf, format: 'yaml' });
console.log(result); // Outputs YAML with the selected option

Example with anyOf

const schemaWithAnyOf = {
  type: 'object',
  anyOf: [
    { properties: { skill: { type: 'string', description: 'A skill' } } },
    { properties: { hobby: { type: 'string', description: 'A hobby' } } }
  ],
};

const result = await objectFromSchema({ schema: schemaWithAnyOf, format: 'json' });
console.log(result); // Outputs JSON with multiple selected options

Acknowledgement

This library makes use of the yaml library to construct YAML documents. Many thanks to the developers of the yaml package for their contributions to simplifying YAML manipulations in JavaScript.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  schema:
    type:
      - string
      - object
    description: The JSON schema to base the user prompts on.
  ref:
    type:
      - string
      - object
    description: Optional reference object or file path/URL to use for default values.
  format:
    type: string
    enum:
      - json
      - yaml
      - all
    default: json
    description: The format of the output. Can be 'json', 'yaml', or 'all'.