Is there any way to use a relative file path for JSON schemas ?
Below mentioned syntax not work in vscode :
$schema = "file:///foo.schema.json"
And this one works :
$schema = "file:///c:/test/foo.schema.json"
If you have a scheme like file:, that forms a full (absolute) URI, instead of a (relative) URI Reference.
A full URI is supposed to mean the same thing everywhere, so it doesn't make sense to have a relative file path. Also note that file:///foo.schema.json is the same thing as file://localhost/foo.schema.json
To write a relative filename, use a URI Reference, like foo.schema.json. This will be resolved against a URI base — typically the URI of the document — to form the correct URI, even if the file moves on the filesystem.
For example, if you use this in a file at c:\test\main.json, then the Base URI will be file:///c:/test/main.json, and the URI Reference will resolve to file:///c:/test/foo.schema.json, which is correct.
See File Uri Scheme and Relative Files for more information on this.
Related
I am trying to refer to schema located in a sub folder with $ref, I wanted to put as optional a couple of other schema files into my root schema file. I have seen about cross file reference and in file referencing with $ref, but wanted to check if an entire schema file/files can be referenced by folder. ie. for eg:
./subfolder/{...}.json
contains a list of schema files and in my root schema file i would like to reference them like
"$ref": "./subfolder/"
I am assuming, I could expand a schema file infinitely using a format like this. Thank for your answer and time.
It's better described as cross-resource referencing. JSON Schema has no notion of files or folders or file systems.
Instead, it does have the notion of URIs and URI resolution.
The approach you should take is to give each schema resource (contained in a JSON file), a full URI using $id. Then use full (or relative) references. You can use relative references if your URIs all use the same first parts (protocol and domain for example).
The implementation you're using should allow you to load in multiple schemas OR provide a means to resolve references using a user-defined function.
The usual approach is to load in all schemas, and then allow the URI references to resolve based on an index of $id.
Once you've loaded a schema into an implementation, it won't know the file it originally came from (if any), and can only rely on the URIs provided in the schema itself. Your schemas may define URIs as if they were available at different paths, but ultimately you COULD store them all in the same folder regardless.
I was wondering if index.html is a relative URL or not.
I know that Website/Pages/index.html is a URL. But what if it was just the file name and file extension without the path? Would it still be called a URL?
Both of your examples are relative paths, not urls.
Relative url examples:
Suppliers
<IMG src="../icons/logo.gif" alt="logo">
<IMG src="image/logo.gif" alt="logo">
A relative URL (defined in [RFC1808]) doesn't contain any protocol or
machine information. Its path generally refers to a resource on the
same machine as the current document. Relative URLs may contain
relative path components (".." means one level up in the hierarchy
defined by the path), and may contain fragment identifiers.
SRC: http://www.w3.org/TR/WD-html40-970917/htmlweb.html
URL Definition:
URL is an acronym for Uniform Resource Locator and is a reference (an
address) to a resource on the Internet. A URL has two main components:
Protocol identifier: For the URL http://example.com , the protocol
identifier is http . Resource name: For the URL http://example.com ,
the resource name is example.com.
SRC: https://docs.oracle.com/javase/tutorial/networking/urls/definition.html (this is a url)
Absolute path:
/home/you/index.html
Relative path:
you/index.html
index.html
Absolute and relative paths
An absolute or full path points to the same location in a file system
regardless of the current working directory. To do that, it must
contain the root directory.
By contrast, a relative path starts from some given working directory,
avoiding the need to provide the full absolute path. A filename can be
considered as a relative path based at the current working directory.
If the working directory is not the file's parent directory, a file
not found error will result if the file is addressed by its name.
SRC: http://en.wikipedia.org/wiki/Path_(computing)
What a path relative URL is
And, yes, index.html can be a relative url.
When referring to a file that occurs in the same directory as the referring page, a URL can be as simple as the name of the file
If you want to link to your index.html page from your about.html page, as long as they're in the same directory you could very simply do:
Index
What i think you are confusing is absolute vs relative paths. As other's are describing, a URL with an absolute path needs to be defined by:
protocol: (http://)
domain: (bobsjingles.)
extension: (edu)
directory path: (/journeycovers)
fragment: (/index.html)
http://bobsjingles.edu/journeycovers/index.html
All that absolute path does (essentially) is point to an IP / port on a machine, where you can send a request under a specific protocol (http), and get an expected data result (html.)
In a HTTP URL like http://example.com/index.html, /index.html is the URL’s path.
HTTP URLs don’t "know" or care about file names or file extensions.
There is no conceptual difference between paths like /index.html, /index_html, /index, /index/foo/html, or /foooo. (Servers, on the other hand, might use various conventions, like appending a dot followed by a file extension, to do something if such a URL is requested.)
URL is an acronym for Uniform Resource Locator and is a reference (an address) to a resource on the Internet.
Having said that, a file name with its extension is not a URL as it is not enough to determine the location of the file on the internet.
However, a file name and its extension can be referred to as a URI.
URI can be a locator (http://example.com) or a filename (example.txt) and the combination of both is the URL (and can still be called a URI).
Here is the complete RFC3986 for your reference.
Read this article to help you understand more the difference between URIs and URLs along with some examples
I'm trying to use Swagger to create API documentation for an API we're building and I've never used it before.
The documentation on Github says that the Resources Listing needs t be at /api-docs and the various resource files need to be at /api-docs/books etc.
This makes naming files and folders very tricky. I think they expect the files to have no file names, rather than having a folder called /api-docs it has to be an extension-less file, then you can't put the resources in an api-docs folder because you can't call the folder that, so they suggest using a folder called /listings.
This folder doesn't appear in the URL structure of your documentation though, it's kind of invisible because you set the baseURL in your resources to the proper path, but it looks like that has to be an absolute path, which is awkward if you want to have it on several servers (local and production).
Maybe I just don't get it but this all seems to be absolutely nuts.
So, I have 2 questions.....
1) Can I give my resource listing file and my resource files a .json extension? This would make sense as it's a JSON file.
2) Can I use a relative path to the resource listing file in the baseURL in my resource files?
Ideally, my file structure would be flatter, like this...
/api-docs
resources.json
books.json
films.json
Is Swagger flexible enough to do this?
It's an IIS server if that makes any difference (if the solution requires routing for example).
I was able to put model files into a folder under the web root and could reference them like this.
$ref: '/models/model.yml#/MyObject'
Relative paths also worked without a leading slash.
$ref: 'models/model.yml#/MyObject'
Inside the model.yml, I can reference other objects int eh same file like this
$ref: '#/MyObject2'.
However, I could only get the main swagger file to import model files. I could not get one model file to cross-reference another model file.
I was using a Tomcat web server but the principle will be the same.
I created a file and named it as test.txt. The file contains the following:
<!DOCTYPE html>
<body>
Testing ...
</body>
When I point a browser to it, the content of the file is not rendered. If I renamed the file to test.htm, it gets displayed correctly, i.e., w/o the markup symbols. Would someone please explain the significance of the suffix, or point me some documentation regarding that? Thank you.
On a file system, the file extension is to determine what type of data is stored in a file.
In an HTTP URI, it is meaningless … however if you are mapping URLs onto a file system (the usual method of serving static content) then the web server will use the file extension to determine the Content-Type HTTP response header which is used by the browser to determine the type of data.
I want to use the correct term to make my API as intuitive as possible, so when a parameter is expected to be a full path and filename (ex "C:\Users\Max\Documents\MyDocument.txt") what is the correct term?
filename - that would just be MyDocument.txt, right?
path - that would just be C:\Users\Max\Documents, right?
What should I use for the parameter name? Would "file" be the appropriate name?
I feel kind of dumb asking this, but I want to make sure it's right.
My suggestion would be "Absolute file path" for some path pointing to a file, where as i would use "Absolute directory path" for a path pointing to a directory
In case of relative paths the change should be obvious.
If nothing else, you can always make a section in your documentation where you describe the meaning of certain terms you use.
The correct term is "Fully Qualified Name" (sometimes "FQN").
The term you should use in your API is "QualifiedName" or "QualifiedFilename"
Wikipedia has an entry for "Fully qualified file name" and defines it as "a file on a computer whose exact name is completely specified such that it is unambiguous and cannot be mistaken for any other file on that system."
A term often overused for this is URI, though your example isn't really one of those. I think you'll be perfectly clear if you just use "filepath" or "pathname."
For example, Java's file object uses "pathname" as the parameter name for the constructor on their File object.
Usually path is the full C:\Users\Max\Documents\MyDocument.txt while the C:\Users\Max\Documents\ part is usually known as the base directory or just directory.
You'll see in a lot of example code people write: C:\path\to\the\document.txt
I'd go with fullPath like you said path would be C:\Users\Max\Documents but reading fullPath would suggest path + filename.
I don't think there is One True Answer, maybe some consensus, but that's all we can hope for. I usually try to follow the conventions of the library I'm using (e.g., Cocoa, Java, or PHP). If I've got nothing to go by, I'd say:
File: the abstract thing being referred to by a name: the file handle
Path: a string indicating the location of a file or directory, either absolute or relative: /Users/Max/Documents/FooBar, ../Sibling/Zardoz
Name: the name of the file or directory, without location: FooBar, Zardoz, Documents
One easier solution you may have considered already is telling the consumer of the API what is expected in the XML documentation, which will also appear in Visual Studio intellisense if your compile the assembly with documentation, and distribute the .xml file.
/// <summary>
/// Saves the provided file to disk.
/// </summary>
/// <param name="filePath">The full path, including the filename of the file.</param>
public void SaveFile(string filePath)
{
}