-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathjson-schema-ref-parser.javascript.txt
126 lines (103 loc) · 7.53 KB
/
json-schema-ref-parser.javascript.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ JSON-SCHEMA-REF-PARSER ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
ALTERNATIVES ==> # - json-schema-ref-parser (prefered): can customize parsers, loaders, good at circular ref
# - whitlockjc json-refs: good features, has options for pre-processing, post-processing,
# filtering, has CLI tool, good at notifying of errors
VERSION ==> #11.9.3
#Handles JSON references: parsing, resolving, dereferencing (including circular refs)
#Name suggests "JSON schema" but it's for any JSON
┌──────────┐
│ BASE │
└──────────┘
REF #JSON reference [URI][#HASH] where #HASH is absolute JSON pointer
#As opposed to spec, can be { $ref STR, ... } in which case ... is shallowly merged in
#(reference's properties have less priority than referer's properties)
STEPS ==> #Resolution:
# - find reference, local or remote (i.e. fetches), but do not parse them (e.g. as BUFFER)
# - current|starting document is also added as a local reference
#Parsing: file parsing, e.g. JSON|YAML to JavaScript OBJ
#Dereferencing: replace $ref by reference
PROMISE ==> #All function that return a PROMISE can use final callback instead too.
new RefParser()->REFPARSER #
RefParser.*(...) #Same as (new RefParser).*(...)
┌────────────────┐
│ RESOLUTION │
└────────────────┘
REFPARSER.resolve
(OBJ|PATH|URL[, POPTS])->>REFS #Does resolution
REFPARSER.$refs REFS #From last REFPARSER.*() after resolution
REFS.get(REF)->VAL #
REFS.set(REF, VAL) #
REFS.exists(REF)->BOOL #
REFS.values|toJSON
(["URI_SCHEME"[_ARR]])
->{ REF: VAL, ... } #
REFS.paths(["URI_SCHEME"[_ARR]])
->REF_ARR #
RESOLVER #Plugin handling resolution
#Default ones:
# - file: order 100, for PATH or file:URI, using FS.readFile(), returns BUFFER
# - http: order 200, for http[s]:, using HTTP[S].get(),
# can use RESOLVER.headers|timeout|redirects|withCredentials, returns BUFFER
POPTS.resolve.RSOLVR RESOLVER|BOOL#
RESOLVER.read|order|canRead|* #Similar to PARSER.parse|order|canParse|*
POPTS.resolve.external BOOL #If false (def: true), ignore REF that have a URI part
┌─────────────┐
│ PARSING │
└─────────────┘
REFPARSER.parse
(OBJ|PATH|URL[, POPTS])->>OBJ #Does parsing
PARSER #Plugin handling parsing
#Default ones:
# - json: order 100, on *.json, using JSON.parse()
# - yaml: order 200, on *.yaml|yml|json, using YAML.safeLoad() with js-yaml
# - text: order 300, on *.txt|htm|html|md|xml|js|min|map|css|scss|less|svg
# - binary: order 400, on *.jpeg|jpg|gif|png|bmp|ico, returning BUFFER as is
POPTS.parse.PARSER PARSER|BOOL #PARSER merges properties of PARSER, i.e. to either specify custom one,
#or customize default ones
PARSER.parse(FILE, REFS)->>VAL #Main logic
PARSER.order NUM #Order of execution between each PARSER
PARSER.canParse VAL #Decide whether a given PARSER will be picked. Can be:
# - BOOL
# - REGEXP, against URI
# - ".EXT"[_ARR]
# - FUNC(FILE)->BOOL
#If none matches, try every PARSER until one's parse() method succeeds
PARSER.allowEmpty BOOL #If false (def: true) and parsed value is undefined|{}|[]|""|emptyBUFFER,
#rejects parsing PROMISE.
#Note: default parser can give undefined for yaml|json, "" for text, empty BUFFER for binary.
PARSER.encoding STR #Def: 'utf8'
#Only for 'text'
PARSER.allowBOM BOOL #Def: true
#Only for 'json'
PARSER.* #Any custom property for a given PARSER
FILE.url URI #
FILE.extension ".EXT" #
FILE.hash STR #
FILE.data VAL #What was returned by resolver, usually BUFFER but could theoretically be STR
POPTS.continueOnError #BOOL (def: true). Throw error on first error, instead of error with all errors as ERROR.errors
┌───────────────────┐
│ DEREFERENCING │
└───────────────────┘
REFPARSER.dereference|bundle #Does parsing and resolution and deferencing
(OBJ|PATH|URL[, POPTS])->>OBJ #See below for difference
REFPARSER.schema OBJ #From last REFPARSER.*() after parsing|resolution|dereferencing
POPTS.dereference.circular #What to do when dereferencing circular refs (with REFPARSER.dereference()) among:
# - true (def): create circular references in JavaScript, which works,
# but won't work when serializing to JSON
# - false: throws ReferenceError
# - "ignore": do not dereference file that contains circular refs
#Can also use REFPARSER.bundle(), in which case circular refs are converted to local refs.
REFS.circular #BOOL: whether there are some circular references
POPTS.deference.onCircular #FUNC(STR) called on each circular $ref STR
POPTS.dereference.
excludePathMatcher('PATH')->BOOL #Exclude deferencing specific paths
POPTS.deference.onDereference #FUNC(STR, VAL, OBJ, 'PROP') called on each $ref STR, that resolves to OBJ.PROP VAL
POPTS.dereference
.preservedProperties #'PROP'_ARR (def: []). If { $ref, PROP }, keep PROP after deferencing $ref
POPTS.dereference
.externalReferenceResolution #Whether paths are relative to reference ('relative', def) or cwd ('root')
POPTS.dereference
.mutateInputSchema #BOOL (def: true). Whether to directly mutate OBJ passed to REFPARSER.dereference()
POPTS.dereference.timeoutMs #NUM (def: none)