SchemaDrivenDocumentProcessors Schema does not match documentation
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 11m
- Merged PRs (30d)
- 10
Description
**Operating System**: `Windows`
**DocFX Version Used**: `2.57`
**Template used**: `default`
**Steps to Reproduce**:
1. Define Schema where [PropertyObject](https://dotnet.github.io/docfx/spec/docfx_document_schema.html#property-object) has multiple Types like `"type": [ "integer" , "string" ]`
2. Run docfx
**Expected Behavior**:
[Documentation](https://dotnet.github.io/docfx/spec/docfx_document_schema.html#61-type) 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
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](https://github.com/dotnet/docfx/blob/054d4f6a834dd7b6cfe6b609f5938531095876d6/schemas/v1.0/schema.json#L32) should be replaced with following content:
```json
"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
```
Contributor guide
Assessment
This issue has not been assessed yet.