75 lines
2.7 KiB
C#
75 lines
2.7 KiB
C#
using System;
|
|
using System.Collections.Generic;
|
|
using System.Threading;
|
|
using System.Threading.Tasks;
|
|
|
|
namespace Svrnty.CQRS.Events.Abstractions.Schema;
|
|
|
|
/// <summary>
|
|
/// Generates JSON Schema (Draft 7) definitions from CLR types.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// JSON Schemas enable:
|
|
/// - External consumers (non-.NET clients) to understand event structure
|
|
/// - Schema validation for incoming/outgoing events
|
|
/// - Documentation generation
|
|
/// - Code generation for other languages
|
|
/// </para>
|
|
/// <para>
|
|
/// <strong>Implementation Notes:</strong>
|
|
/// This is an optional service. If not registered, events will be stored
|
|
/// without JSON Schema metadata. This is fine for .NET-to-.NET communication
|
|
/// but limits interoperability with non-.NET systems.
|
|
/// </para>
|
|
/// </remarks>
|
|
public interface IJsonSchemaGenerator
|
|
{
|
|
/// <summary>
|
|
/// Generates a JSON Schema (Draft 7) for the specified CLR type.
|
|
/// </summary>
|
|
/// <param name="type">The CLR type to generate schema for.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>JSON Schema as a string (JSON format).</returns>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// The generated schema should follow JSON Schema Draft 7 specification.
|
|
/// Include property names, types, required fields, and descriptions from
|
|
/// XML documentation comments if available.
|
|
/// </para>
|
|
/// </remarks>
|
|
Task<string> GenerateSchemaAsync(
|
|
Type type,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Validates a JSON string against a JSON Schema.
|
|
/// </summary>
|
|
/// <param name="jsonData">The JSON data to validate.</param>
|
|
/// <param name="jsonSchema">The JSON Schema to validate against.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>True if valid, false otherwise.</returns>
|
|
/// <remarks>
|
|
/// <para>
|
|
/// This is an optional operation. Implementations may throw
|
|
/// <see cref="NotSupportedException"/> if validation is not supported.
|
|
/// </para>
|
|
/// </remarks>
|
|
Task<bool> ValidateAsync(
|
|
string jsonData,
|
|
string jsonSchema,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Gets detailed validation errors if validation fails.
|
|
/// </summary>
|
|
/// <param name="jsonData">The JSON data to validate.</param>
|
|
/// <param name="jsonSchema">The JSON Schema to validate against.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>List of validation error messages, empty if valid.</returns>
|
|
Task<IReadOnlyList<string>> GetValidationErrorsAsync(
|
|
string jsonData,
|
|
string jsonSchema,
|
|
CancellationToken cancellationToken = default);
|
|
}
|