Json Schema | Getters are incorrectly included in properties and required lists

[Mithos5r]

First of all, thank you for the incredible work on this package and for adding the JSON Schema generation feature. It's a huge time-saver that previously had to be done manually, and it's very much appreciated!

When using the new createJsonSchema: true experimental feature, read-only getters are being included in the generated JSON Schema. Furthermore, these getters are being marked as required, even when they are not part of the class constructor and cannot be passed during deserialization.

Currently, there are the fields includeFromJson and includeToJson, but the field includeSchema is missing. These are currently ignored for the schema.

To Reproduce Given the following data structure:

import 'package:json_annotation/json_annotation.dart';

part 'tree.g.dart';

@JsonSerializable(createJsonSchema: true)
final class Tree {
  final List<Branch> branches;
  final List<Root> roots;
  @JsonKey(unknownEnumValue: TreeType.tree)
  final TreeType type;
  final String? customName;
  final int insideHollows;

  const Tree({
    required this.branches,
    required this.roots,
    required this.type,
    required this.customName,
    required this.insideHollows,
  });
}

@JsonSerializable(createJsonSchema: true)
final class Branch {
  final double length;
  final List<Branch> branch;

  const Branch({required this.length, required this.branch});

  factory Branch.fromJson(Map<String, dynamic> json) => _$BranchFromJson(json);

  // This getter should NOT be in the schema, especially as required
  @JsonKey(includeFromJson: false, includeToJson: false, required: false)
  double get proportion => length / branch.length;
}

@JsonEnum(alwaysCreate: true)
enum TreeType { pine, birch, cherry_tree, tree }

Observed Output: In the generated tree.g.dart, the _$BranchJsonSchema includes proportion in the required list:

const _$BranchJsonSchema = {
  r'$schema': 'https://json-schema.org/draft/2020-12/schema',
  'type': 'object',
  'properties': {
    'length': {'type': 'number'},
    'branch': {
      'type': 'array',
      'items': {r'$ref': r'#/$defs/Branch'},
    },
    'proportion': {'type': 'number'}, // Should not be here if it's a getter
  },
  'required': ['length', 'branch', 'proportion'], // 'proportion' is incorrectly marked as required
};

Expected Behavior

• Getters Exclusion: Fields that are not parameters in the primary constructor (like getters) should not be included in the JSON Schema properties by default, or at the very least, should not be in the required list.
• Annotation Respect: The schema generator should respect @jsonkey(includeFromJson: false)
• Feature Request: It would be beneficial to have a specific flag like includeJsonSchema: bool in @jsonkey for granular control.

JSON Schema is often used to validate input before calling fromJson, including read-only getters as required makes the schema validation fail for valid payloads that only contain constructor-required data

[kevmoo]

@Mithos5r – please review and validate your use cases! #1550

[Mithos5r]

Hi @kevmoo!!! Thanks for the update and for the PR! I’ve tested the changes using the specific commit 34c88d8 from the branch, and I can confirm that it partially solves the issue.

However, I found that the fix doesn't seem to propagate when a class is used as a dependency (nested) within another class.

What is working
The standalone schema for the class (e.g., _$RootJsonSchema) is now correct. The getter proportion is properly excluded from both properties and required. 🚀

The remaining issue: Inconsistency in $defs
When a class (like Tree) references other classes (Branch or Root), the generated $defs section still contains the old, incorrect logic. The getters are still being included and marked as required within those definitions.

Example from _$TreeJsonSchema using the PR code:

// The definition inside $defs still includes 'proportion' as required
r'$defs': {
 'Root': {
   'type': 'object',
   'properties': {
     'length': {'type': 'number'},
     'branch': {r'$ref': r'#/$defs/List'}, // Also, notice the List reference here
     'absorptionCoefficient': {'type': 'number'},
     'proportion': {'type': 'number'}, // Should not be here
   },
   'required': ['length', 'branch', 'absorptionCoefficient', 'proportion'], // Should not include 'proportion'
 },
},

Nullable fields marked as required?
I also noticed that in the Tree schema, customName (which is a nullable String? in Dart) is now included in the required list:

'required': ['branches', 'roots', 'type', 'customName', 'insideHollows'],

Since customName is optional/nullable, it probably shouldn't be in the required array of the JSON Schema.

Summary
The fix works for the "main" class schema, but the logic used to generate the internal definitions in $defs (when classes are nested) seems to be using the old implementation or skipping the filter for getters.

Complete generation of __$TreeJsonSchema_:

// The definition inside $defs still includes 'proportion'
const _$TreeJsonSchema = {
 r'$schema': 'https://json-schema.org/draft/2020-12/schema',
 'type': 'object',
 'properties': {
   'branches': {
     'type': 'array',
     'items': {r'$ref': r'#/$defs/Branch'},
   },
   'roots': {
     'type': 'array',
     'items': {r'$ref': r'#/$defs/Root'},
   },
   'type': {'type': 'object'},
   'customName': {'type': 'string'},
   'insideHollows': {'type': 'integer'},
 },
 'required': ['branches', 'roots', 'type', 'customName', 'insideHollows'],
 r'$defs': {
   'Branch': {
     'type': 'object',
     'properties': {
       'length': {'type': 'number'},
       'branch': {r'$ref': r'#/$defs/List'},
       'proportion': {'type': 'number'},
     },
     'required': ['length', 'branch', 'proportion'],
   },
   'Root': {
     'type': 'object',
     'properties': {
       'length': {'type': 'number'},
       'branch': {r'$ref': r'#/$defs/List'},
       'absorptionCoefficient': {'type': 'number'},
       'proportion': {'type': 'number'},
     },
     'required': ['length', 'branch', 'absorptionCoefficient', 'proportion'],
   },
 },
};

[kevmoo]

@Mithos5r – please check the PR now and comment if you have any issues.

[Mithos5r]

@kevmoo

I have verified the latest changes and I can confirm:

1. Getters fix: The getters (proportion) are now correctly excluded from the $defs section. It works perfectly.

2. Required fields: Regarding my previous comment about customName, I realized it was my mistake—I had it marked as required in the constructor. Removing required from the Dart constructor correctly removes it from the JSON Schema.

Reviewing the latest version, I have noticed that the internal reference within $ref is broken. This is outside the current scope, but I believe it is important because the schema validators will not work.

Nested List Reference Issue
Inside the $defs section, properties that are Lists (like branch inside Branch) are being generated with a broken reference:

r'$defs': {
   'Branch': {
     'type': 'object',
     'properties': {
       'length': {'type': 'number'},
       'branch': {r'$ref': r'#/$defs/List'}, // This reference is broken/undefined
       'proportion': {'type': 'number'},
     },
     'required': ['length', 'branch', 'proportion'],
   },
   'Root': {
     'type': 'object',
     'properties': {
       'length': {'type': 'number'},
       'branch': {r'$ref': r'#/$defs/List'}, // This reference is broken/undefined
       'absorptionCoefficient': {'type': 'number'},
       'proportion': {'type': 'number'},
     },
     'required': ['length', 'branch', 'absorptionCoefficient', 'proportion'],
   },
 },

The generator seems to lose the type context inside the definition and defaults to List instead of generating an array with the correct items reference (like it does in the top-level schema).

...
'branches': {
     'type': 'array',
     'items': {r'$ref': r'#/$defs/Branch'},
   },
   'roots': {
     'type': 'array',
     'items': {r'$ref': r'#/$defs/Root'},
   },
...

Since this issue was originally about Getters, would you prefer me to open a separate issue for this "List reference" bug to keep the discussion clean?

Thanks again for the amazing support!

[kevmoo]

@Mithos5r – you're VERY nice to ask.

Uh. Yeah, let's do a follow-up w/ the new issue bits. I want to land the PR and get this closed. Thanks.

[kevmoo]

@Mithos5r – just published latest w/ the fixes. PTAL!