SchemaDrivenDocumentProcessors Schema does not match documentation

[Herrmel]

Operating System: Windows

DocFX Version Used: 2.57

Template used: default

Steps to Reproduce:

1. Define Schema where PropertyObject has multiple Types like "type": [ "integer" , "string" ]
2. Run docfx

Expected Behavior: Documentation says

The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique.

so it should be fine and work.

Actual Behavior:

Once I execute docfx it says:

Error:[BuildCommand.LoadSchemaDrivenDocumentProcessors](PowerShell.schema.json)Schema validation failed. Please validate the file and make sure it conforms to schema 'DocFX document schema meta-schema' (https://github.com/dotnet/docfx/schemas/v1.0/schema.json)

The current schema in docfx does not allow multiple Types. So if I have a yml where a value can be 0 and 1 (theone), I get a validationerror with type string as well as with type integer. If docfx really does support multiple Types you should fix the schema.json: this line should be replaced with following content:

"anyOf":[
  { 
    "$ref": "#/definitions/simpleTypes"
  },
  {
    "type":"array",
    "items": { "$ref": "#/definitions/simpleTypes" }
  }
]

Example for Testing

Shema: ```json { "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", "id": "PowerShell", "version": "1", "type": "object", "properties": { "examples": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "contentType": "default" }, "preCode": { "type": "string", "contentType": "markdown" }, "code": { "type": "string", "contentType": "default" }, "postCode": { "type": "string", "contentType": "markdown" } } } }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "contentType": "default" }, "description": { "type": "string", "contentType": "markdown" } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "contentType": "href" }, "text": { "type": "string", "contentType": "default" } } } }, "module": { "type": "object", "properties": { "name": { "type": "string", "contentType": "default" } } }, "name": { "type": "string" }, "notes": { "type": "string", "contentType": "markdown" }, "optionalParameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "contentType": "default" }, "aliases": { "type": "array", "items": { "type": "string", "contentType": "default" } }, "defaultValue": { "type": "string", "contentType": "default" }, "description": { "type": "string", "contentType": "markdown" }, "parameterValueGroup": { "type": "array", "items": { "type": "string", "contentType": "default" } }, "pipelineInput": { "type": "string", "contentType": "default" }, "position": { "type": "integer" }, "type": { "type": "string", "contentType": "default" } } } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "contentType": "default" }, "description": { "type": "string", "contentType": "markdown" } } } }, "requiredParameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "contentType": "default" }, "aliases": { "type": "array", "items": { "type": "string", "contentType": "default" } }, "defaultValue": { "type": "string", "contentType": "default" }, "description": { "type": "string", "contentType": "markdown" }, "parameterValueGroup": { "type": "array", "items": { "type": "string", "contentType": "default" } }, "pipelineInput": { "type": "string", "contentType": "default" }, "position": { "type": [ "integer" , "string" ] }, "type": { "type": "string", "contentType": "default" } } } }, "remarks": { "type": "string", "contentType": "markdown" }, "summary": { "type": "string", "contentType": "markdown" }, "syntaxes": { "type": "array", "items": { "type": "object", "properties": { "parameterValueGroup": { "type": "string", "contentType": "default" }, "parameters": { "type": "array", "items": { "type": "string" } }, "IsDefault": { "type": "boolean" } } } } } } ``` example yml: ```yml ### YamlMime:PowerShell examples: - name: Beispiel 1 preCode: '' code: PS FIS:\> ConvertTo-Type "10°C" ([Temperature]) postCode: Dieses Beispiel zeigt wie ein Temperature-Objekt aus einem Text erzeugt werden kann. - name: Beispiel 2 preCode: '' code: PS FIS:\> ConvertTo-Type "10°C" "Fis.Runtime.ValueTypes.Thermodynamic.Temperature,Fis.Runtime.ValueTypes" postCode: Alternativ kann der Typ, wie in diesem Beispiel, auch über seinen voll qualifizierenden Namen angegeben werden. inputs: - type: Object description: Das zu konvertierenden Objekt kann über eine pipe an ConvertTo-FisType gesendet werden. links: [] module: name: FisRuntime name: ConvertTo-FisType notes: Damit eine erfolgreiche Konvertierung gelingt muss ein Converter für den ObjektTyp zum entsprechenden Typ vorhanden sein. Dies kann zum Beispiel über ein Attribut oder über das manuelle Eintragen eines neuen Converters geschehen. optionalParameters: [] outputs: - type: Object description: Das konvertierte Objekt vom entsprechenden Typ. requiredParameters: - name: InputObject aliases: [] defaultValue: None description: Das zu konvertierende Objekt. Hier ist jeder Wert erlaubt, auch $null. parameterValueGroup: [] pipelineInput: True (ByPropertyName, ByValue) position: 1 type: Object - name: TargetType aliases: [] defaultValue: None description: Der Typ, in den das Objekt konvertiert werden soll. parameterValueGroup: [] pipelineInput: 'False' position: 2 type: Type - name: TargetTypeIdentifier aliases: [] defaultValue: None description: Der eindeutige Identifizierer für einen Typ. Dieser besteht aus folgendem Muster '{vollständiger Typname},{Assemblyname}'. parameterValueGroup: [] pipelineInput: 'False' position: Named type: String remarks: '`ConvertTo-Type` versucht ein Objekt in einen bestimmten Typ zu konvertieren.' summary: Ein Objekt in einen bestimmten Typ konvertieren. syntaxes: - parameterValueGroup: ExplicitType parameters: - InputObject - TargetType - parameterValueGroup: NamedType parameters: - InputObject - TargetTypeIdentifier ```

[Herrmel]

@superyyrrzz do you know if this is already supported within docfx? If so I could create a PR if you want to.

[superyyrrzz]

@Herrmel No, this is not supported. This is a documentation bug. Docfx v3 will support AnyOf, but it does not release yet: https://github.com/dotnet/docfx/blob/4988e8732cf22e5f327c3f74b09bb44af91cac8a/src/docfx/lib/schema/JsonSchema.cs#L201

[Herrmel]

ok, thank you for clarification. I tried using v3 but I found it hard to understand the configurationoptions from the bare yml stuff so I decided to wait for a release with some documentation on usage. Is there any ETA for v3? It's been a long time in development and I kinda lost hope waiting for it since Updates on github are really rare (Roadmaps last update was Jul 2020 and the Project stuff from Github for v3 was moved to a internal Ressource I think).