@artinet/metadata-validator/README.md

a tool to validate metadata

# @artinet/metadata-validator

<!-- [![npm version](https://badge.fury.io/js/%40artinet%2Fmetadata-validator.svg)](https://badge.fury.io/js/%40artinet%2Fmetadata-validator) -->

A TypeScript library for validating Artinet service registration metadata against the official JSON schema.

This validator ensures that metadata provided during service registration conforms to the expected structure, formats, and constraints defined by the Artinet protocol.

## Features

-   Validates metadata against the current Artinet registration JSON schema.
-   Provides clear error messages for validation failures.
-   Supports validation of both plain JavaScript objects and JSON strings.
-   Exports the underlying JSON schema and a generated Zod schema for advanced use cases.
-   Written in TypeScript with type definitions included.

## Installation

```bash
npm install @artinet/metadata-validator
# or
yarn add @artinet/metadata-validator
```

## Usage

```typescript
import { MetadataValidator } from "@artinet/metadata-validator";
import type { IRegistration } from "@artinet/metadata-validator"; // Optional: For type safety

// 1. Create an instance of the validator
const validator = new MetadataValidator();

// 2. Define your metadata object (or load from a file/API)
const serviceMetadata: IRegistration = {
    // ... your registration metadata fields ...
    schemaVersion: "1.0.0",
    serviceName: "My Example Service",
    description: "This service does amazing things.",
    version: "1.0.1",
    capabilities: ["data-analysis", "ml-inference"],
    communication: {
        endpoints: [{ url: "https://api.example.com/service" }]
    },
    publicKey: {
        kty: "RSA",
        n: "...", // RSA modulus
        e: "AQAB" // RSA public exponent
    },
    contact: {
        email: "tech@example.com"
    }
    // ... other fields as needed ...
};

// 3. Validate the metadata
const result = validator.validateMetadata(serviceMetadata);

// 4. Check the result
if (result.isValid) {
    console.log("Metadata is valid!");
    // result.serviceName and result.tags are available on success
    console.log("Service Name (lowercase):", result.serviceName);
    console.log("Extracted Tags:", result.tags);
} else {
    console.error("Metadata is invalid:");
    // Use formatErrors for user-friendly output
    const formattedErrors = validator.formatErrors(result.errors);
    formattedErrors.forEach(err => console.error(`- ${err}`));
    // Raw errors are also available:
    // console.error("Raw errors:", result.errors);
}

// You can also validate a JSON string directly:
const jsonMetadata = JSON.stringify(serviceMetadata);
const resultFromString = validator.validateMetadata(jsonMetadata);
console.log("Validation result from string:", resultFromString.isValid);

```

### Validation Result (`IResult`)

The `validateMetadata` method returns an object conforming to the `IResult` interface:

```typescript
interface IResult {
    isValid: boolean;
    errors: ErrorObject[]; // Array of Ajv error objects if invalid
    serviceName?: string; // Lowercase service name if valid
    tags?: string[];      // Extracted tags (serviceName, capabilities, tags) if valid
}
```

### Exported Schemas

For advanced integration or inspection, the package also exports:

-   `schema`: The raw JSON schema object used for validation.
-   `zodRegistrationSchema`: A Zod schema object generated from the JSON schema, useful for runtime parsing and type inference with Zod.

```typescript
import { schema, zodRegistrationSchema } from "@artinet/metadata-validator";

console.log("Raw JSON Schema:", schema);
// Use zodRegistrationSchema with Zod:
// const parsed = zodRegistrationSchema.safeParse(someData);
```

## Development

1.  Clone the repository.
2.  Navigate to this package directory: `cd modules/tools/metadata-validator`
3.  Install dependencies: `npm install`
4.  Build: `npm run build`
5.  Run tests: `npm test`

## Contributing

Contributions are welcome! Please follow standard Git practices (fork, feature branch, pull request). Ensure tests pass (`npm test`) before submitting a PR.

## License

[MIT](LICENSE)