UNPKG

18.9 kBJavaScriptView Raw
1/**
2 * @overview Schema for validating JSDoc doclets.
3 *
4 * @author Michael Mathews <micmath@gmail.com>
5 * @author Jeff Williams <jeffrey.l.williams@gmail.com>
6 * @license Apache License 2.0 - See file 'LICENSE.md' in this project.
7 * @see <http://tools.ietf.org/html/draft-zyp-json-schema-03>
8 */
9'use strict';
10
11// JSON schema types
12var ARRAY = 'array';
13var BOOLEAN = 'boolean';
14var INTEGER = 'integer';
15var NULL = 'null';
16var NUMBER = 'number';
17var OBJECT = 'object';
18var STRING = 'string';
19var UNDEFINED = 'undefined';
20
21var BOOLEAN_OPTIONAL = [BOOLEAN, NULL, UNDEFINED];
22var STRING_OPTIONAL = [STRING, NULL, UNDEFINED];
23
24var EVENT_REGEXP = /event\:[\S]+/;
25var PACKAGE_REGEXP = /package\:[\S]+/;
26
27// information about the code associated with a doclet
28var META_SCHEMA = exports.META_SCHEMA = {
29 type: OBJECT,
30 optional: true,
31 additionalProperties: false,
32 properties: {
33 code: {
34 type: OBJECT,
35 additionalProperties: false,
36 properties: {
37 funcscope: {
38 type: STRING,
39 optional: true
40 },
41 id: {
42 type: STRING,
43 optional: true
44 },
45 name: {
46 optional: true
47 },
48 node: {
49 type: OBJECT,
50 optional: true
51 },
52 paramnames: {
53 type: ARRAY,
54 optional: true,
55 uniqueItems: true,
56 items: {
57 type: STRING
58 }
59 },
60 type: {
61 type: STRING,
62 optional: true
63 },
64 value: {
65 optional: true
66 }
67 }
68 },
69 filename: {
70 title: 'The name of the file that contains the code associated with this doclet.',
71 type: STRING,
72 optional: true
73 },
74 lineno: {
75 title: 'The line number of the code associated with this doclet.',
76 type: NUMBER,
77 optional: true
78 },
79 path: {
80 title: 'The path in which the code associated with this doclet is located.',
81 type: STRING,
82 optional: true
83 },
84 range: {
85 title: 'The positions of the first and last characters of the code associated with ' +
86 'this doclet.',
87 type: ARRAY,
88 optional: true,
89 minItems: 2,
90 maxItems: 2,
91 items: {
92 type: NUMBER
93 }
94 },
95 vars: {
96 type: OBJECT
97 }
98 }
99};
100
101// type property containing type names
102var TYPE_PROPERTY_SCHEMA = exports.TYPE_PROPERTY_SCHEMA = {
103 type: OBJECT,
104 additionalProperties: false,
105 properties: {
106 names: {
107 type: ARRAY,
108 minItems: 1,
109 items: {
110 type: STRING
111 }
112 },
113 // type parser output
114 parsedType: {
115 type: OBJECT,
116 additionalProperties: true
117 }
118 }
119};
120
121// enumeration properties
122var ENUM_PROPERTY_SCHEMA = exports.ENUM_PROPERTY_SCHEMA = {
123 type: OBJECT,
124 additionalProperties: false,
125 properties: {
126 comment: {
127 type: STRING
128 },
129 defaultvalue: {
130 optional: true
131 },
132 description: {
133 type: STRING_OPTIONAL,
134 optional: true
135 },
136 kind: {
137 type: STRING,
138 // TODO: get this from a real enum somewhere
139 enum: ['member']
140 },
141 longname: {
142 type: STRING
143 },
144 memberof: {
145 type: STRING,
146 optional: true
147 },
148 meta: META_SCHEMA,
149 name: {
150 type: STRING
151 },
152 // is this member nullable? (derived from the type expression)
153 nullable: {
154 type: BOOLEAN_OPTIONAL
155 },
156 // is this member optional? (derived from the type expression)
157 optional: {
158 type: BOOLEAN_OPTIONAL
159 },
160 scope: {
161 type: STRING,
162 // TODO: get this from a real enum somewhere
163 enum: ['static']
164 },
165 type: TYPE_PROPERTY_SCHEMA,
166 // can this member be provided more than once? (derived from the type expression)
167 variable: {
168 type: BOOLEAN_OPTIONAL
169 }
170 }
171};
172
173// function parameter, or object property defined with @property tag
174var PARAM_SCHEMA = exports.PARAM_SCHEMA = {
175 type: OBJECT,
176 additionalProperties: false,
177 properties: {
178 // what is the default value for this parameter?
179 defaultvalue: {
180 optional: true
181 },
182 // a description of the parameter
183 description: {
184 type: STRING_OPTIONAL,
185 optional: true
186 },
187 // what name does this parameter have within the function?
188 name: {
189 type: STRING
190 },
191 // can the value for this parameter be null?
192 nullable: {
193 type: BOOLEAN_OPTIONAL,
194 optional: true
195 },
196 // is a value for this parameter optional?
197 optional: {
198 type: BOOLEAN_OPTIONAL,
199 optional: true
200 },
201 // what are the types of value expected for this parameter?
202 type: TYPE_PROPERTY_SCHEMA,
203 // can this parameter be repeated?
204 variable: {
205 type: BOOLEAN_OPTIONAL,
206 optional: true
207 }
208 }
209};
210
211var DOCLET_SCHEMA = exports.DOCLET_SCHEMA = {
212 type: OBJECT,
213 additionalProperties: false,
214 properties: {
215 // what access privileges are allowed
216 access: {
217 type: STRING,
218 optional: true,
219 // TODO: define this as an enumeration elsewhere
220 enum: [
221 'private',
222 'protected',
223 'public'
224 ]
225 },
226 alias: {
227 type: STRING,
228 optional: true
229 },
230 augments: {
231 type: ARRAY,
232 optional: true,
233 uniqueItems: true,
234 items: {
235 type: STRING
236 }
237 },
238 author: {
239 type: ARRAY,
240 optional: true,
241 items: {
242 type: STRING
243 }
244 },
245 borrowed: {
246 type: ARRAY,
247 optional: true,
248 uniqueItems: true,
249 items: {
250 type: OBJECT,
251 additionalProperties: false,
252 properties: {
253 // name of the target
254 as: {
255 type: STRING,
256 optional: true
257 },
258 // name of the source
259 from: {
260 type: STRING
261 }
262 }
263 }
264 },
265 // a description of the class that this constructor belongs to
266 classdesc: {
267 type: STRING,
268 optional: true
269 },
270 comment: {
271 type: STRING
272 },
273 copyright: {
274 type: STRING,
275 optional: true
276 },
277 defaultvalue: {
278 optional: true
279 },
280 defaultvaluetype: {
281 type: STRING,
282 optional: true,
283 enum: [OBJECT, ARRAY]
284 },
285 // is usage of this symbol deprecated?
286 deprecated: {
287 type: [STRING, BOOLEAN],
288 optional: true
289 },
290 // a description
291 description: {
292 type: STRING_OPTIONAL,
293 optional: true
294 },
295 // something else to consider
296 examples: {
297 type: ARRAY,
298 optional: true,
299 items: {
300 type: STRING
301 }
302 },
303 exceptions: {
304 type: ARRAY,
305 optional: true,
306 items: PARAM_SCHEMA
307 },
308 // the path to another constructor
309 extends: {
310 type: ARRAY,
311 optional: true,
312 uniqueItems: true,
313 items: {
314 type: STRING
315 }
316 },
317 // the path to another doc object
318 fires: {
319 type: ARRAY,
320 optional: true,
321 uniqueItems: true,
322 items: {
323 type: STRING,
324 pattern: EVENT_REGEXP
325 }
326 },
327 forceMemberof: {
328 type: BOOLEAN_OPTIONAL,
329 optional: true
330 },
331 ignore: {
332 type: BOOLEAN,
333 optional: true
334 },
335 implementations: {
336 type: ARRAY,
337 optional: true,
338 items: {
339 type: STRING
340 }
341 },
342 implements: {
343 type: ARRAY,
344 optional: true,
345 items: {
346 type: STRING
347 }
348 },
349 inheritdoc: {
350 type: STRING,
351 optional: true
352 },
353 inherited: {
354 type: BOOLEAN,
355 optional: true
356 },
357 inherits: {
358 type: STRING,
359 optional: true,
360 dependency: {
361 inherited: true
362 }
363 },
364 isEnum: {
365 type: BOOLEAN,
366 optional: true
367 },
368 // what kind of symbol is this?
369 kind: {
370 type: STRING,
371 // TODO: define this as an enumeration elsewhere
372 enum: [
373 'class',
374 'constant',
375 'event',
376 'external',
377 'file',
378 'function',
379 'interface',
380 'member',
381 'mixin',
382 'module',
383 'namespace',
384 'package',
385 'param',
386 'typedef'
387 ]
388 },
389 license: {
390 type: STRING,
391 optional: true
392 },
393 listens: {
394 type: ARRAY,
395 optional: true,
396 uniqueItems: true,
397 items: {
398 type: STRING,
399 pattern: EVENT_REGEXP
400 }
401 },
402 longname: {
403 type: STRING
404 },
405 // probably a leading substring of the path
406 memberof: {
407 type: STRING,
408 optional: true
409 },
410 // information about this doc
411 meta: META_SCHEMA,
412 // was this doclet mixed in?
413 mixed: {
414 type: BOOLEAN,
415 optional: true
416 },
417 mixes: {
418 type: ARRAY,
419 optional: true,
420 uniqueItems: true,
421 items: {
422 type: STRING
423 }
424 },
425 // probably a trailing substring of the path
426 name: {
427 type: STRING
428 },
429 // is this member nullable? (derived from the type expression)
430 nullable: {
431 type: BOOLEAN_OPTIONAL
432 },
433 // is this member optional? (derived from the type expression)
434 optional: {
435 type: BOOLEAN_OPTIONAL
436 },
437 // does this member explicitly override the parent?
438 override: {
439 type: BOOLEAN,
440 optional: true
441 },
442 overrides: {
443 type: STRING,
444 optional: true
445 },
446 // are there function parameters associated with this doc?
447 params: {
448 type: ARRAY,
449 optional: true,
450 uniqueItems: true,
451 items: PARAM_SCHEMA
452 },
453 preserveName: {
454 type: BOOLEAN,
455 optional: true
456 },
457 properties: {
458 type: ARRAY,
459 optional: true,
460 uniqueItems: true,
461 minItems: 1,
462 items: {
463 anyOf: [ENUM_PROPERTY_SCHEMA, PARAM_SCHEMA]
464 }
465 },
466 readonly: {
467 type: BOOLEAN,
468 optional: true
469 },
470 // the symbol being documented requires another symbol
471 requires: {
472 type: ARRAY,
473 optional: true,
474 uniqueItems: true,
475 minItems: 1,
476 items: {
477 type: STRING
478 }
479 },
480 returns: {
481 type: ARRAY,
482 optional: true,
483 minItems: 1,
484 items: PARAM_SCHEMA
485 },
486 // what sort of parent scope does this symbol have?
487 scope: {
488 type: STRING,
489 enum: [
490 // TODO: make these an enumeration
491 'global',
492 'inner',
493 'instance',
494 'static'
495 ]
496 },
497 // something else to consider
498 see: {
499 type: ARRAY,
500 optional: true,
501 minItems: 1,
502 items: {
503 type: STRING
504 }
505 },
506 // at what previous version was this doc added?
507 since: {
508 type: STRING,
509 optional: true
510 },
511 summary: {
512 type: STRING,
513 optional: true
514 },
515 // arbitrary tags associated with this doc
516 tags: {
517 type: ARRAY,
518 optional: true,
519 minItems: 1,
520 items: {
521 type: OBJECT,
522 additionalProperties: false,
523 properties: {
524 originalTitle: {
525 type: STRING
526 },
527 text: {
528 type: STRING,
529 optional: true
530 },
531 title: {
532 type: STRING
533 },
534 value: {
535 type: [STRING, OBJECT],
536 optional: true,
537 properties: PARAM_SCHEMA
538 }
539 }
540 }
541 },
542 'this': {
543 type: STRING,
544 optional: true
545 },
546 todo: {
547 type: ARRAY,
548 optional: true,
549 minItems: 1,
550 items: {
551 type: STRING
552 }
553 },
554 // extended tutorials
555 tutorials: {
556 type: ARRAY,
557 optional: true,
558 minItems: 1,
559 items: {
560 type: STRING
561 }
562 },
563 // what type is the value that this doc is associated with, like `number`
564 type: TYPE_PROPERTY_SCHEMA,
565 undocumented: {
566 type: BOOLEAN,
567 optional: true
568 },
569 // can this member be provided more than once? (derived from the type expression)
570 variable: {
571 type: BOOLEAN_OPTIONAL
572 },
573 variation: {
574 type: STRING,
575 optional: true
576 },
577 // what is the version of this doc
578 version: {
579 type: STRING,
580 optional: true
581 },
582 // is a member left to be implemented during inheritance?
583 virtual: {
584 type: BOOLEAN,
585 optional: true
586 }
587 }
588};
589
590var CONTACT_INFO_SCHEMA = exports.CONTACT_INFO_SCHEMA = {
591 type: OBJECT,
592 additionalProperties: false,
593 properties: {
594 email: {
595 type: STRING,
596 optional: true
597 },
598 name: {
599 type: STRING,
600 optional: true
601 },
602 url: {
603 type: STRING,
604 optional: true,
605 format: 'uri'
606 }
607 }
608};
609
610var BUGS_SCHEMA = exports.BUGS_SCHEMA = {
611 type: OBJECT,
612 additionalProperties: false,
613 properties: {
614 email: {
615 type: STRING,
616 optional: true
617 },
618 url: {
619 type: STRING,
620 optional: true,
621 format: 'uri'
622 }
623 }
624};
625
626var PACKAGE_SCHEMA = exports.PACKAGE_SCHEMA = {
627 type: OBJECT,
628 additionalProperties: false,
629 properties: {
630 author: {
631 anyOf: [STRING, CONTACT_INFO_SCHEMA],
632 optional: true
633 },
634 bugs: {
635 anyOf: [STRING, BUGS_SCHEMA],
636 optional: true
637 },
638 contributors: {
639 type: ARRAY,
640 optional: true,
641 minItems: 0,
642 items: {
643 anyOf: [STRING, CONTACT_INFO_SCHEMA]
644 }
645 },
646 dependencies: {
647 type: OBJECT,
648 optional: true
649 },
650 description: {
651 type: STRING,
652 optional: true
653 },
654 devDependencies: {
655 type: OBJECT,
656 optional: true
657 },
658 engines: {
659 type: OBJECT,
660 optional: true
661 },
662 files: {
663 type: ARRAY,
664 uniqueItems: true,
665 minItems: 0,
666 items: {
667 type: STRING
668 }
669 },
670 homepage: {
671 type: STRING,
672 optional: true,
673 format: 'uri'
674 },
675 keywords: {
676 type: ARRAY,
677 optional: true,
678 minItems: 0,
679 items: {
680 type: STRING
681 }
682 },
683 kind: {
684 type: STRING,
685 enum: ['package']
686 },
687 licenses: {
688 type: ARRAY,
689 optional: true,
690 minItems: 1,
691 items: {
692 type: OBJECT,
693 additionalProperties: false,
694 properties: {
695 type: {
696 type: STRING,
697 optional: true
698 },
699 url: {
700 type: STRING,
701 optional: true,
702 format: 'uri'
703 }
704 }
705 }
706 },
707 longname: {
708 type: STRING,
709 optional: true,
710 pattern: PACKAGE_REGEXP
711 },
712 main: {
713 type: STRING,
714 optional: true
715 },
716 name: {
717 type: STRING,
718 optional: true
719 },
720 repository: {
721 type: OBJECT,
722 optional: true,
723 additionalProperties: false,
724 properties: {
725 type: {
726 type: STRING,
727 optional: true
728 },
729 // we don't use `format: 'uri'` here because repo URLs are atypical
730 url: {
731 type: STRING,
732 optional: true
733 }
734 }
735 },
736 version: {
737 type: STRING,
738 optional: true
739 }
740 }
741};
742
743var DOCLETS_SCHEMA = exports.DOCLETS_SCHEMA = {
744 type: ARRAY,
745 items: {
746 anyOf: [DOCLET_SCHEMA, PACKAGE_SCHEMA]
747 }
748};