@fnet/object-from-schema v0.1.18

@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.

Developer Guide for @fnet/object-from-schema

Overview

The @fnet/object-from-schema library simplifies the generation of objects adhering to a specified JSON Schema. Its main purpose is to create YAML or JSON formatted outputs by guiding users through schema-based inputs, automatically incorporating predefined defaults or existing references. This is particularly useful for generating configuration files or data entry forms governed by a schema, without manually inputting every detail.

Installation

To install the library, use either npm or yarn:

npm install @fnet/object-from-schema

or

yarn add @fnet/object-from-schema

Usage

The core function of the @fnet/object-from-schema library is index, which enables you to generate an object formatted as JSON or YAML from a given JSON Schema. You can also include default values through a reference object.

Example Usage

First, import the library in your JavaScript file:

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

Basic Example

Suppose you have a JSON schema and want to generate a configuration file in YAML format:

const schema = {
  type: "object",
  properties: {
    name: { type: "string", description: "Your name" },
    age: { type: "number", description: "Your age", default: 30 },
    email: { type: "string", description: "Your email address" }
  },
  required: ["name", "email"]
};

// Call the function with the schema, optional ref object, and desired format
objectFromSchema({ schema, format: "yaml" })
  .then(yamlOutput => {
    console.log(yamlOutput);
  })
  .catch(error => {
    console.error('Error creating object from schema:', error);
  });

With Reference Object

You can also use an existing reference to prepopulate some of the fields:

const ref = {
  name: "John Doe",
  email: "john.doe@example.com"
};

// Generate YAML output with reference values
objectFromSchema({ schema, ref, format: "yaml" })
  .then(yamlOutput => {
    console.log(yamlOutput);
  })
  .catch(error => {
    console.error('Error creating object from schema:', error);
  });

This will prompt for missing or optional fields not filled by the ref object.

Examples

JSON Output

Generate an object in JSON format:

objectFromSchema({ schema, format: "json" })
  .then(jsonOutput => {
    console.log(jsonOutput);
  });

Handling oneOf and Nested Objects

The function can manage nested properties and schemas with oneOf:

const complexSchema = {
  type: "object",
  properties: {
    address: {
      type: "object",
      properties: {
        street: { type: "string", description: "Street address" },
        city: { type: "string", description: "City" }
      }
    },
    contact: {
      oneOf: [
        { properties: { phone: { type: "string", description: "Phone number" }}},
        { properties: { email: { type: "string", description: "Email address" }}}
      ]
    }
  }
};

// Use the schema
objectFromSchema({ schema: complexSchema, format: "yaml" })
  .then(yamlOutput => {
    console.log(yamlOutput);
  });

Acknowledgement

This library does not require specific acknowledgements but was developed using well-established JavaScript practices and libraries for YAML manipulation and user prompting.

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'.